From 5b0e856e796f4d28ec121806dc1632b5933c47f5 Mon Sep 17 00:00:00 2001 From: Tom Daykin Date: Fri, 12 Oct 2018 09:15:52 +0000 Subject: [PATCH 1/3] 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. + From 6774634c3c93358b4c72e5b410e849a0d791ae66 Mon Sep 17 00:00:00 2001 From: Tom Daykin Date: Sat, 13 Oct 2018 14:55:19 +0000 Subject: [PATCH 2/3] Added recommendations Signed-off-by: Tom Daykin --- README.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index e4b25ca..3cf032d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -## Documentation & User Guides + ## Documentation & User Guides This repo is the source for the official [Pi-hole documentation](https://docs.pi-hole.net/). @@ -8,27 +8,21 @@ To add a new link on the navigation panel you need to edit the `mkdocs.yml` file To add a new document or guide. - Navigate to the directory where it will be hosted. - EG. guides are in `REPO/docs/guides` + EG. guides are in `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. +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 +Please make sure you fork the repo and change the clone URL in the example below for your fork: + +```bash +git clone https://github.com/YOUR-USERNAME/docs cd docs sudo pip install mkdocs sudo pip install mkdocs-material markdown-include mkdocs serve --dev-addr 0.0.0.0:8000 ``` - -#### 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. - From 5f50c95af71bdaf48ca84d6f591fad545c7e598e Mon Sep 17 00:00:00 2001 From: Tom Daykin Date: Mon, 15 Oct 2018 11:47:11 +0000 Subject: [PATCH 3/3] Fixed spacing problems Signed-off-by: Tom Daykin --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 3cf032d..d31023f 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,21 @@ - ## Documentation & User Guides +## Documentation & User Guides This repo is the source for the official [Pi-hole documentation](https://docs.pi-hole.net/). -#### How to contribute. +### 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. +To add a new document or guide. -- Navigate to the directory where it will be hosted. +- Navigate to the directory where it will be hosted. EG. guides are in `docs/guides` -- Create the file using a URL friendly filename. +- 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. +### 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. Please make sure you fork the repo and change the clone URL in the example below for your fork: