Front matter extraction
mkdocs.yml
# 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
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.
Output
site/
├── drone_develop/
│ └── index.html
├── fibo/
│ └── index.html
└── index.html
drone_develop
Developing
You can clone the repository with
git clone https://this_is_a_dummy_url
You can build the distribution with
pip install build
python -m build .
That will produce a .whl
file in the dist
subdirectory.
fibo
This paragraph is here to make sure the extraction starts immediately.
Coffee Fibonacci
Although trite, this is an example of the sum recurrence.
Complexity
This note about complexity will appear in the doc page.
Last update:
August 25, 2023