From 5b0e856e796f4d28ec121806dc1632b5933c47f5 Mon Sep 17 00:00:00 2001 From: Tom Daykin Date: Fri, 12 Oct 2018 09:15:52 +0000 Subject: [PATCH] Revised repo Readme] Signed-off-by: Tom Daykin --- README.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 8dd03f0..e4b25ca 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,23 @@ -If you want to work on this repo, you can preview the site as you work. +## Documentation & User Guides + +This repo is the source for the official [Pi-hole documentation](https://docs.pi-hole.net/). + +#### How to contribute. +To add a new link on the navigation panel you need to edit the `mkdocs.yml` file in the root of the repo. There is a guide for building the navbar [on the mkdocs wiki]( https://www.mkdocs.org/user-guide/configuration/#nav) + +To add a new document or guide. + +- Navigate to the directory where it will be hosted. + EG. guides are in `REPO/docs/guides` +- Create the file using a URL friendly filename. + EG. `docs/guides/url-friendly.md` +- Edit your document using Markdown, there are loads of resources available for the correct syntax. + + +#### Testing your changes. +Whilst working on this repo, it is advised that you review your own changes locally before commiting them. This can be done by using the `mkdocs serve` command. Linux Mint / Ubuntu instructions: - ``` git clone git@github.com:pi-hole/docs.git cd docs @@ -10,9 +26,9 @@ sudo pip install mkdocs-material markdown-include mkdocs serve --dev-addr 0.0.0.0:8000 ``` -Deploying to GitHub pages: +#### Deploying to GitHub pages: ``` mkdocs gh-deploy ``` MkDocs will build the docs and use the `ghp-import` tool to commit them to our `gh-pages` branch and also automatically push the `gh-pages` branch to GitHub. -Warning: Be aware that you will not be able to review the built site before it is pushed to GitHub! Therefore, you **must** verify any changes you make to the docs beforehand by using the `mkdocs serve` command and reviewing the built files locally. +