Update Docs

docs/contributing/.pages

@@ -1,3 +1,3 @@
 nav:
-  - Introduction: index.md
+  - Guidelines: guidelines.md
   - Contributors: contributors.md

docs/contributing/contributors.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Contributors
-nav_order: 1
+nav_order: 2
 has_children: false
 parent: Contributing
 has_toc: false
@@ -22,7 +22,7 @@ has_toc: false
         <a href="https://github.com/actions-user">
             <img src="https://avatars1.githubusercontent.com/u/65916846?v=4" width="100;" alt="actions-user"/>
             <br />
-            <sub><b>actions-user</b></sub>
+            <sub><b>Actions-user</b></sub>
         </a>
     </td></tr>
 </table>

docs/contributing/index.md → docs/contributing/guidelines.md

@@ -1,7 +1,12 @@
 ---
-layout: default title: Introduction nav_order: 7 has_children: true has_toc: false
+layout: default
+title: Guidelines
+nav_order: 1
+has_children: false
+parent: Contributing
+has_toc: false
 ---
-# Contributing
+# Guidelines
 
 If contributing with code, please leave the pedantic mode ON (` -DBUILD_WITH_PEDANTIC_WARNINGS=ON`),
 use [cppcheck](http://cppcheck.sourceforge.net), and [clang-format](https://clang.llvm.org/docs/ClangFormat.html).

docs/gallery.md

@@ -1,5 +1,9 @@
 ---
-layout: default title: Gallery nav_order: 6 has_children: false has_toc: false
+layout: default
+title: Gallery
+nav_order: 6
+has_children: false
+has_toc: false
 ---
 # Gallery
 

docs/installing/binaries.md

@@ -8,7 +8,9 @@ has_toc: false
 ---
 # Binaries
 
-Get the latest release from the [Release Page](https://GitHub.com/alandefreitas/mdsplit/releases/) or download the latest binaries from the [CI Artifacts](https://github.com/alandefreitas/mdsplit/actions?query=workflow%3A%22Build+mdsplit%22+event%3Apush).
+Get the latest release from the [Release Page](https://GitHub.com/alandefreitas/mdsplit/releases/) or download the
+latest binaries from
+the [CI Artifacts](https://github.com/alandefreitas/mdsplit/actions?query=workflow%3A%22Build+mdsplit%22+event%3Apush).
 
 
 

docs/installing/install-from-source.md

@@ -1,7 +1,11 @@
 ---
-layout: default title: Install from Source nav_order: 2 has_children: false parent: Installing has_toc: false
+layout: default
+title: Install from Source
+nav_order: 2
+has_children: false
+parent: Installing
+has_toc: false
 ---
-
 # Install from Source
 
 To install from the source files:

docs/options/front-matter.md

@@ -1,5 +1,10 @@
 ---
-layout: default title: Front matter nav_order: 6 has_children: false parent: Options has_toc: false
+layout: default
+title: Front matter
+nav_order: 6
+has_children: false
+parent: Options
+has_toc: false
 ---
 # Front matter
 

docs/options/hiding-sections.md

@@ -0,0 +1,45 @@
+---
+layout: default
+title: Hiding sections
+nav_order: 2
+has_children: false
+parent: Options
+has_toc: false
+---
+# Hiding sections
+
+Use the comments `<!-- START mdsplit-ignore -->` and `<!-- END mdsplit-ignore -->` to ignore sections from
+your `README.md`. For instance:
+
+=== "Markdown"
+
+    ```md
+    <!-- START mdsplit-ignore -->
+    # Section to ignore
+
+    `mdsplit` will remove this whole section from your documentation.
+
+    <!-- END mdsplit-ignore -->
+    ```
+
+or
+
+=== "Markdown"
+
+    ```md
+    # Section to ignore
+
+    <!-- START mdsplit-ignore -->
+    `mdsplit` will remove this paragraph from your documentation.
+    <!-- END mdsplit-ignore -->
+    ```
+
+If you ignore the complete section, `mdsplit` will create no file for that section.
+
+If you're reading this from [`README.md`](https://github.com/alandefreitas/mdsplit/blob/master/README.md) you will see this section has a subsection that will be completely
+ignored in the documentation.
+
+
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/options/index.md

@@ -1,5 +1,9 @@
 ---
-layout: default title: Introduction nav_order: 4 has_children: true has_toc: false
+layout: default
+title: Introduction
+nav_order: 4
+has_children: true
+has_toc: false
 ---
 # Options
 

docs/options/input-file.md

@@ -1,5 +1,10 @@
 ---
-layout: default title: Input file nav_order: 3 has_children: false parent: Options has_toc: false
+layout: default
+title: Input file
+nav_order: 3
+has_children: false
+parent: Options
+has_toc: false
 ---
 # Input file
 

docs/options/links-to-repository.md

@@ -30,7 +30,8 @@ should become
 
 so that the link works correctly on GitHub pages.
 
-You can use the `--repository` (or `-r`) option to provide the repository `mdsplit` should consider to generate these links:
+You can use the `--repository` (or `-r`) option to provide the repository `mdsplit` should consider to generate these
+links:
 
 ```bash
 mdsplit -r alandefreitas/matplotplusplus

docs/options/output-directory.md

@@ -1,5 +1,10 @@
 ---
-layout: default title: Output directory nav_order: 4 has_children: false parent: Options has_toc: false
+layout: default
+title: Output directory
+nav_order: 4
+has_children: false
+parent: Options
+has_toc: false
 ---
 # Output directory
 

docs/options/remove-html-tags.md

@@ -1,5 +1,10 @@
 ---
-layout: default title: Remove HTML Tags nav_order: 5 has_children: false parent: Options has_toc: false
+layout: default
+title: Remove HTML Tags
+nav_order: 5
+has_children: false
+parent: Options
+has_toc: false
 ---
 # Remove HTML Tags
 

docs/quick-start.md

@@ -0,0 +1,38 @@
+---
+layout: default
+title: Quick Start
+nav_order: 2
+has_children: false
+has_toc: false
+---
+# Quick Start
+
+Go to your repository settings and turn on GitHub Pages on the branch gh-pages.
+
+![Turn on GitHub Pages](images/turonpages.png)
+
+Copy the [`mkdocs.yml`](https://github.com/alandefreitas/mdsplit/blob/master/mkdocs.yml) file to your repository:
+
+??? info "See contents"
+
+    === "mkdocs.yml"
+
+        ```yaml hl_lines="1 2 3 4 6 30"
+        --8<-- "mkdocs.yml"
+        ```
+
+Copy the [`.github/workflows/docs.yml`](https://github.com/alandefreitas/mdsplit/blob/master/mkdocs.yml) file to your repository:
+
+??? info "See contents"
+
+    === "docs.yml"
+
+        ```yaml hl_lines="21 22 31-44 48"
+        --8<-- ".github/workflows/docs.yml"
+        ```
+
+In a few seconds, your README.md file will become a beautiful documentation.
+
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/step-by-step/.pages

@@ -0,0 +1,4 @@
+nav:
+  - Splitting Locally: splitting-locally.md
+  - Testing Locally: testing-locally.md
+  - Github Actions: github-actions.md

docs/step-by-step/github-actions.md

@@ -0,0 +1,37 @@
+---
+layout: default
+title: Github Actions
+nav_order: 3
+has_children: false
+parent: Step-by-Step
+has_toc: false
+---
+# Github Actions
+
+You can integrate `mdsplit` with GitHub actions to regenerate the documentation whenever you change your `README.md`
+file.
+
+Use this workflow to get started:
+
+=== ".github/workflows/docs.yml"
+
+    ```yaml hl_lines="21 22 31-44 48"
+    --8<-- ".github/workflows/docs.yml"
+    ```
+
+Replace the settings with your repository information.
+
+Most steps in this workflow are optional:
+
+* The step `technote-space/toc-generator@v2` creates a table of contents for your README.md file
+* The second step downloads and builds the master version of mdsplit. This is the version we use in this repository, but
+  you probably want to use a more stable version in your own repository. To do that, comment this step and use the third
+  and forth steps instead.
+* The third and fourth steps (commented out) download the latest release version of mdsplit. That's probably what you
+  want for your repository. Uncomment these steps to do that.
+* The next steps are pushing the docs to your master branch. Make any adjustments you might need.
+* The last steps are taking the docs from your master branch and publishing them to your gh-pages branch.
+
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/step-by-step/splitting-locally.md

@@ -0,0 +1,25 @@
+---
+layout: default
+title: Splitting Locally
+nav_order: 1
+has_children: false
+parent: Step-by-Step
+has_toc: false
+---
+# Splitting Locally
+
+After [installing](../installing/binaries.md) `mdsplit`, run
+
+```bash
+mdsplit -r username/repository
+```
+
+from your project root directory to generate your documentation.
+
+`mdsplit` will split your `README.md` file into smaller files and save the results to the `docs` directory.
+
+!!! note This is directory from where mkdocs will later build your documentation.
+
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/step-by-step/testing-locally.md

@@ -0,0 +1,43 @@
+---
+layout: default
+title: Testing Locally
+nav_order: 2
+has_children: false
+parent: Step-by-Step
+has_toc: false
+---
+# Testing Locally
+
+You might want to test your documentation locally before pushing it to your repository.
+
+Install mkdocs with
+
+```bash
+pip install mkdocs-material
+```
+
+After generating the docs with mdsplit, run the mkdocs server with
+
+```bash
+mkdocs serve
+```
+
+Or build the static documentation with
+
+```bash
+mkdocs serve
+```
+
+Use this mkdocs configuration file to get started:
+
+=== "mkdocs.yml"
+
+```yaml hl_lines="1 2 3 4 6 30"
+--8<-- "mkdocs.yml"
+```
+
+Replace the settings with your repository information.
+
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->