Add example readme files (#416)

.github/workflows/test.yml

@@ -50,3 +50,5 @@ jobs:
         uses: athackst/htmlproofer-action@main
         with:
           directory: "./site"
+      - name: Check for diffs
+        run: git diff --exit-code

examples/ok-mkdocs-custom-extract/README.md

@@ -0,0 +1,106 @@
+<!-- md-ignore -->
+<!-- DO NOT EDIT! This file is auto-generated from README.md.ninja -->
+# Front matter extraction
+
+## mkdocs.yml
+
+```yaml
+# This example shows how to set up custom extraction modes. Litcoffee files
+# consist of interspersed Markdown and Coffeescript code. The pattern
+# defined here extracts a documentation page from each such file, consisting of:
+# everything from the beginning of the file to the first line of code
+# (a line indented by at least four spaces), together with any later Markdown
+# block preceded by a comment containing `# DOCPAGE`.
+#
+# Similarly, you may want to have to have a custom extraction even for a
+# standard file pattern, or for one particular file; the `drone.yml` pattern
+# could for example extract development documentation from a Drone yml file.
+# Note this latter pattern takes advantage of the fact that you can have just
+# a single top-level block of parameters in an `extract:` section.
+site_name: ok-mkdocs-custom-extract
+plugins:
+  - simple:
+      semiliterate:
+        - pattern: '\.litcoffee'
+          extract:
+            - {stop: '^\s{4,}\S'}  # No start, so active from beginning
+            - {start: '# DOCPAGE', stop: '^\s{4,}\S'}
+        - pattern: 'drone.yml'
+          destination: 'drone_develop.md'
+          extract:
+            start: '### develop'
+            stop: '^\s*###'
+            replace: ['^# (.*\s*)$', '^\s*-(.*\s*)$']
+```
+## Input
+
+```
+ok-mkdocs-custom-extract/
+├── drone.yml
+├── fibo.litcoffee
+├── mkdocs.yml
+└── README.md
+```
+
+
+**fibo.litcoffee**
+```.litcoffee
+{% raw %}
+This paragraph is here to make sure the extraction starts immediately.
+# Coffee Fibonacci
+
+Although trite, this is an example of the sum recurrence.
+
+    fib = (n) ->
+      # Base cases
+      if n in [ 1 , 2 ]
+        return 1
+      # Recursive calls
+      fib(n-1) + fib(n-2)
+
+## Example usage
+This is perfectly good Markdown commentary, but will not appear in the
+extracted doc page.
+
+    fib(3) # => fib(2) + fib(1) => 2
+
+    # DOCPAGE
+## Complexity
+This note about complexity will appear in the doc page.
+
+{% endraw %}
+```
+
+
+## Output
+
+```
+site/
+├── drone_develop/
+│   └── index.html
+├── fibo/
+│   └── index.html
+└── index.html
+```
+
+
+<div class="admonition quote">
+<p class="admonition-title">drone_develop</p>
+<h2 id="developing">Developing</h2>
+<h1 id="_1"></h1>
+<p>You can clone the repository with</p>
+<pre><code>git clone https://this_is_a_dummy_url
+</code></pre>
+<p>You can build the distribution with</p>
+<pre><code> pip install build
+ python -m build .
+</code></pre>
+<p>That will produce a <code>.whl</code> file in the <code>dist</code> subdirectory.</p></div>
+
+<div class="admonition quote">
+<p class="admonition-title">fibo</p>
+<p>This paragraph is here to make sure the extraction starts immediately.</p>
+<h1 id="coffee-fibonacci">Coffee Fibonacci</h1>
+<p>Although trite, this is an example of the sum recurrence.</p>
+<h2 id="complexity">Complexity</h2>
+<p>This note about complexity will appear in the doc page.</p></div>

examples/ok-mkdocs-docs-extensions/README.md

@@ -0,0 +1,32 @@
+<!-- md-ignore -->
+<!-- DO NOT EDIT! This file is auto-generated from README.md.ninja -->
+# Extra extensions
+
+## mkdocs.yml
+
+```yaml
+# This example shows how extensions are copied to the result
+site_name: ok-mkdocs-docs-extensions
+plugins:
+  - simple:
+      include_extensions: [".txt"]
+```
+## Input
+
+```
+ok-mkdocs-docs-extensions/
+├── mkdocs.yml
+├── README.md
+└── test.txt
+```
+
+
+
+## Output
+
+```
+site/
+├── index.html
+└── test.txt
+```
+

examples/ok-mkdocs-docs-ignore/README.md

@@ -0,0 +1,45 @@
+<!-- md-ignore -->
+<!-- DO NOT EDIT! This file is auto-generated from README.md.ninja -->
+# Ignore a folder
+
+## mkdocs.yml
+
+```yaml
+# This example shows how a subfolder can be ignored.
+site_name: ok-mkdocs-docs-ignore
+plugins:
+  - simple:
+      ignore_folders: ["subfolder"]
+```
+## Input
+
+```
+ok-mkdocs-docs-ignore/
+├── mkdocs.yml
+├── other-folder/
+│   └── subfolder/
+│       ├── draft.md
+│       └── index.md
+├── README.md
+├── subfolder/
+│   ├── draft.md
+│   └── index.md
+└── test.md
+```
+
+
+
+## Output
+
+```
+site/
+├── index.html
+├── other-folder/
+│   └── subfolder/
+│       ├── draft/
+│       │   └── index.html
+│       └── index.html
+└── test/
+    └── index.html
+```
+

examples/ok-mkdocs-docs-include/README.md

@@ -0,0 +1,37 @@
+<!-- md-ignore -->
+<!-- DO NOT EDIT! This file is auto-generated from README.md.ninja -->
+# Only include a specific folder
+
+## mkdocs.yml
+
+```yaml
+# This example shows how to only include from a specific folder
+site_name: ok-mkdocs-docs-include
+plugins:
+  - simple:
+      include_folders: ["subfolder/**"]
+```
+## Input
+
+```
+ok-mkdocs-docs-include/
+├── mkdocs.yml
+├── README.md
+├── subfolder/
+│   ├── draft.md
+│   └── index.md
+└── test.md
+```
+
+
+
+## Output
+
+```
+site/
+└── subfolder/
+    ├── draft/
+    │   └── index.html
+    └── index.html
+```
+

examples/ok-mkdocs-docs-merge/README.md

@@ -0,0 +1,37 @@
+<!-- md-ignore -->
+<!-- DO NOT EDIT! This file is auto-generated from README.md.ninja -->
+# Merge into docs folder
+
+## mkdocs.yml
+
+```yaml
+# This example shows how to merge a docs folder with other documentation.
+site_name: ok-mkdocs-docs-merge
+plugins:
+  - simple
+```
+## Input
+
+```
+ok-mkdocs-docs-merge/
+├── docs/
+│   ├── draft.md
+│   └── index.md
+├── mkdocs.yml
+├── README.md
+└── test.md
+```
+
+
+
+## Output
+
+```
+site/
+├── draft/
+│   └── index.html
+├── index.html
+└── test/
+    └── index.html
+```
+

examples/ok-mkdocs-docs-no-merge/README.md

@@ -0,0 +1,40 @@
+<!-- md-ignore -->
+<!-- DO NOT EDIT! This file is auto-generated from README.md.ninja -->
+# Don't merge docs folder
+
+## mkdocs.yml
+
+```yaml
+# This example shows how to keep the docs folder embedded within your other docs.
+site_name: ok-mkdocs-docs-no-merge
+plugins:
+  - simple:
+        merge_docs_dir: false
+```
+## Input
+
+```
+ok-mkdocs-docs-no-merge/
+├── docs/
+│   ├── draft.md
+│   └── index.md
+├── mkdocs.yml
+├── README.md
+└── test.md
+```
+
+
+
+## Output
+
+```
+site/
+├── docs/
+│   ├── draft/
+│   │   └── index.html
+│   └── index.html
+├── index.html
+└── test/
+    └── index.html
+```
+

examples/ok-mkdocs-ignore-file/README.md

@@ -0,0 +1,59 @@
+<!-- md-ignore -->
+<!-- DO NOT EDIT! This file is auto-generated from README.md.ninja -->
+# Ignore a file
+
+## mkdocs.yml
+
+```yaml
+# This tests if the site directory is ignored in both build and serve.
+site_name: ok-mkdocs-ignore-file
+plugins:
+- simple:
+```
+## Input
+
+```
+ok-mkdocs-ignore-file/
+├── hello_world.cpp
+├── mkdocs.yml
+├── README.md
+└── test.md
+```
+
+
+**hello_world.cpp**
+```.cpp
+{% raw %}
+/** md-ignore
+
+# Ignore me
+
+Ignore everything beyond the first line since it contains md-ignore.
+**/
+
+#include <iostream>
+
+int main() {
+  /** md
+  # Hello world
+
+  This is the main function for hello world.
+  It outputs "Hello World!" to the screen.
+  **/
+    std::cout << "Hello World!";
+    return 0;
+}
+
+{% endraw %}
+```
+
+
+## Output
+
+```
+site/
+├── index.html
+└── test/
+    └── index.html
+```
+