Digital Gardening with Material for MkDocs
Page Status: In Progress (What's this?)
Page Statuses in this Wiki¶
My wiki has the following status system to show how finished the page is that you're currently reading:
- Draft: Rough and early ideas, don't expect too much (especially finished sentences)
- In Progress: Cleaned up and clarified certain sections, some are still unfinished
- Finished: (Mostly) Done and complete, but still checked sometimes
What is Digital Gardening?¶
Digital Gardening is about organizing your thoughts in your website / wiki / knowledge base, and sharing it with others. Compared to blogging, your published content is not sorted chronologically and does not have to be perfect. Instead, it is about publishing your thoughts bit by bit and learning in public.
If you want to read more about this topic, you should definitely check out Maggie Appleton's A Brief History & Ethos of the Digital Garden. After reading her post, I realized that the concept of Digital Gardening fits my workflow for writing documentation, and was able to further improve my wiki.
Status definitions¶
As a Digital Garden contains unfinished drafts and pages that are still worked on, readers should be able to see how "finished" the current page is. Maggie Appleton does this with a categorization system with 3 page states:
- 🌱 Seedlings for very rough and early ideas
- 🌿 Budding for work I’ve cleaned up and clarified
- 🌳 Evergreen for work that is reasonably complete (though I still tend these over time).
The status system of this wiki is inspired by this.
Displaying the Page Status in Material for MkDocs¶
As you might've seen, every page in this wiki has a (admonition) box at the very top that displays the current status of the document. To add this to your own wiki, just follow these steps:
First, define the statuses that you want to use in your mkdocs.yml file. If you want to add a text that links to the explanation of your different statuses, add the values in the status_explanation keys as well.
# ...
extra:
# ...
status:
draft: Draft
wip: In Progress
done: Finished
status_explanation:
text: (What's this?)
url: "docs/digital-gardening"
After that, add the "status" key and the current state of the page to the metadata:
To display the status, create an override at overrides/partials/content.html with the following content. Feel free to change
{% include "partials/tags.html" %}
{% include "partials/actions.html" %}
{% if "\x3ch1" not in page.content %}
<h1>{{ page.title | d(config.site_name, true)}}</h1>
{% endif %}
<!-- This is the snippet that displays the status -->
{% if page.meta and page.meta.status %}
{% if config.extra.status %}
{% if page.meta.status in config.extra.status %}
<div class="admonition info">
<p class="admonition-title">
<span>Page Status: {{ config.extra.status[page.meta.status] }}</span>
{% if config.extra.status_explanation %}
<span>
<a href="{{- config.extra.status_explanation.url | url -}}">{{- config.extra.status_explanation.text -}}</a>
</span>
{% endif %}
</p>
</div>
{% endif %}
{% endif %}
{% endif %}
{{ page.content }}
{% include "partials/source-file.html" %}
{% include "partials/feedback.html" %}
{% include "partials/comments.html" %}