From 96dc80ace4227131bc6886a8b33bcbd9246f39f6 Mon Sep 17 00:00:00 2001 From: "David A. Desrosiers" Date: Mon, 4 Mar 2024 22:32:47 -0500 Subject: [PATCH 1/4] Refactored README.md to use cleaner Markdown and refined the steps to make them clearer --- README.md | 83 ++++++++++++++++++++++++++----------------------------- 1 file changed, 39 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 4ad5090c9..848d21626 100644 --- a/README.md +++ b/README.md @@ -6,73 +6,68 @@ Network-wide ad blocking via your own Linux hardware

-The Pi-hole[®](https://pi-hole.net/trademark-rules-and-brand-guidelines/) is a [DNS sinkhole](https://en.wikipedia.org/wiki/DNS_Sinkhole) that protects your devices from unwanted content, without installing any client-side software. +The Pi-hole® is a [DNS sinkhole](https://en.wikipedia.org/wiki/DNS_Sinkhole) that protects your devices from unwanted content, without installing any client-side software. ## Documentation & User Guides -This repo is the source for the official [Pi-hole documentation](https://docs.pi-hole.net/). +This repository 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) +**Adding a New Link to the Navigation Panel:** +- Edit the `mkdocs.yml` file at the root of the repository. +- Follow the guide for building the navbar on the [MkDocs Wiki](https://www.mkdocs.org/user-guide/configuration/#nav). -To add a new document or guide. +**Adding a New Document or Guide:** +1. Navigate to the appropriate directory (e.g., guides are in `docs/guides`). +2. Create a new file with a URL-friendly filename (e.g., `url-friendly.md`). +3. Use Markdown to edit your document. There are many resources available online for Markdown syntax. -- Navigate to the directory where it will be hosted. - E.g. guides are in `docs/guides` -- Create the file using a URL friendly filename. - E.g. `docs/guides/url-friendly.md` -- Edit your document using Markdown, there are loads of resources available for the correct syntax. +### Testing Your Changes Locally -### Testing your changes +It's advised to review your changes locally before committing. Use the `mkdocs serve` command to live preview your changes on your local machine. -When working on this repo, it is advised that you review your changes locally before committing them. The `mkdocs serve` command can be used to live preview your changes (as you type) on your local machine. - -Please make sure you fork the repo and change the clone URL in the example below for your fork: - -- Linux Mint / Ubuntu 18.04 LTS / 19.10 / 20.04 LTS: - - Preparations (only required once): +**General Steps:** +1. Fork the repository into your own Github account. +2. Clone your fork and navigate into it. You need only do this once: ```bash git clone https://github.com/YOUR-USERNAME/docs cd docs - sudo apt install python3-pip - pip3 install -r requirements.txt ``` - - Running the docs server: +3. Install dependencies: - ```bash - mkdocs serve --dev-addr 0.0.0.0:8000 - ``` + - **Linux Mint / Ubuntu:** (18.04/20.04/22.04 LTS/19.10 and up) -- Fedora Linux instructions (tested on Fedora Linux 28): - - Preparations (only required once): + ```bash + sudo apt install python3-pip + pip3 install -r requirements.txt + ``` - ```bash - git clone https://github.com/YOUR-USERNAME/docs - cd docs - pip install --user -r requirements.txt - ``` + - **Fedora Linux:** (tested on Fedora Linux 28) + + ```bash + pip install --user -r requirements.txt + ``` - - Running the docs server: +4. Run the local docs server: ```bash mkdocs serve --dev-addr 0.0.0.0:8000 ``` -- Docker instructions: - - One-shot run: - - ```bash - docker run -v `pwd`:/opt/app/ -w /opt/app/ -p 8000:8000 -it nikolaik/python-nodejs:python3.7-nodejs16 \ - sh -c "pip install --user -r requirements.txt && \ - /root/.local/bin/mkdocs build && \ - npm ci && \ - npm test && \ - /root/.local/bin/mkdocs serve --dev-addr 0.0.0.0:8000" - ``` +**Docker Instructions:** +For a one-shot run with Docker, use the following command: -After these commands, the current branch is accessible through your favorite browser at +```bash +docker run -v $(pwd):/opt/app/ -w /opt/app/ -p 8000:8000 \ + -it nikolaik/python-nodejs:python3.7-nodejs16 \ + sh -c "pip install --user -r requirements.txt && \ + /root/.local/bin/mkdocs build && \ + npm ci && \ + npm test && \ + /root/.local/bin/mkdocs serve --dev-addr 0.0.0.0:8000" +``` -[![Deploys by Netlify](https://www.netlify.com/img/global/badges/netlify-color-bg.svg)](https://www.netlify.com/) +After running the above, your changes will be accessible through your favorite browser at http://localhost:8000. \ No newline at end of file From 54fa51f9b374d9c922edd6cce5adc411d6acf444 Mon Sep 17 00:00:00 2001 From: "David A. Desrosiers" Date: Mon, 4 Mar 2024 23:22:20 -0500 Subject: [PATCH 2/4] Fixing an issue from Markdown linting that removed a link that had an @ sign as its only anchor. Oops! --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 848d21626..1cc2e2756 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Network-wide ad blocking via your own Linux hardware

-The Pi-hole® is a [DNS sinkhole](https://en.wikipedia.org/wiki/DNS_Sinkhole) that protects your devices from unwanted content, without installing any client-side software. +The Pi-hole[®](https://pi-hole.net/trademark-rules-and-brand-guidelines/) is a [DNS sinkhole](https://en.wikipedia.org/wiki/DNS_Sinkhole) that protects your devices from unwanted content, without installing any client-side software. ## Documentation & User Guides From b909d9763bf1ca27bf581212fd9801f1bcf1cb1e Mon Sep 17 00:00:00 2001 From: "David A. Desrosiers" Date: Tue, 5 Mar 2024 00:14:23 -0500 Subject: [PATCH 3/4] Found another one, truncated from the bottom. Now replaced. --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1cc2e2756..f081d181d 100644 --- a/README.md +++ b/README.md @@ -70,4 +70,6 @@ docker run -v $(pwd):/opt/app/ -w /opt/app/ -p 8000:8000 \ /root/.local/bin/mkdocs serve --dev-addr 0.0.0.0:8000" ``` -After running the above, your changes will be accessible through your favorite browser at http://localhost:8000. \ No newline at end of file +After running the above, your changes will be accessible through your favorite browser at http://localhost:8000. + +[![Deploys by Netlify](https://www.netlify.com/img/global/badges/netlify-color-bg.svg)](https://www.netlify.com/) From d3266dcbef4d7a10540b438b291605baa5f924a5 Mon Sep 17 00:00:00 2001 From: "David A. Desrosiers" Date: Tue, 5 Mar 2024 17:54:15 -0500 Subject: [PATCH 4/4] Sanitizing issues found by markdownlint --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f081d181d..7cece2045 100644 --- a/README.md +++ b/README.md @@ -15,10 +15,12 @@ This repository is the source for the official [Pi-hole documentation](https://d ### How to Contribute **Adding a New Link to the Navigation Panel:** + - Edit the `mkdocs.yml` file at the root of the repository. - Follow the guide for building the navbar on the [MkDocs Wiki](https://www.mkdocs.org/user-guide/configuration/#nav). **Adding a New Document or Guide:** + 1. Navigate to the appropriate directory (e.g., guides are in `docs/guides`). 2. Create a new file with a URL-friendly filename (e.g., `url-friendly.md`). 3. Use Markdown to edit your document. There are many resources available online for Markdown syntax. @@ -28,6 +30,7 @@ This repository is the source for the official [Pi-hole documentation](https://d It's advised to review your changes locally before committing. Use the `mkdocs serve` command to live preview your changes on your local machine. **General Steps:** + 1. Fork the repository into your own Github account. 2. Clone your fork and navigate into it. You need only do this once: @@ -70,6 +73,6 @@ docker run -v $(pwd):/opt/app/ -w /opt/app/ -p 8000:8000 \ /root/.local/bin/mkdocs serve --dev-addr 0.0.0.0:8000" ``` -After running the above, your changes will be accessible through your favorite browser at http://localhost:8000. +After running the above, your changes will be accessible through your favorite browser at . [![Deploys by Netlify](https://www.netlify.com/img/global/badges/netlify-color-bg.svg)](https://www.netlify.com/)