An example website created using mkdocs
Install
pip install mkdocs-material
E:\mkdocs>mkdocs new doc-as-code
INFO - Creating project directory: doc-as-code
INFO - Writing config file: doc-as-code\mkdocs.yml
INFO - Writing initial docs: doc-as-code\docs\index.md
E:\mkdocs>code doc-as-code
Do any changes and the changes would reflect
Lets create the following, folders and file
Lets add tables.js under javascripts folder
app.document$.subscribe(function() {
var tables = document.querySelectorAll("article table")
tables.forEach(function(table) {
new Tablesort(table)
})
})
Lets add app-theme.css under styles.
/* Progress Bars */
.md-typeset
.progress-label {
position: absolute;
text-align: center;
font-weight: 700;
width: 100%;
margin: 0;
line-height: 1.2rem;
white-space: nowrap;
overflow: hidden;
}
.progress-bar {
height: 1.2rem;
float: left;
background-color: #2979ff;
}
.candystripe-animate .progress-bar {
animation: animate-stripes 3s linear infinite;
}
.progress {
display: block;
width: 100%;
margin: 0.5rem 0;
height: 1.2rem;
background-color: #eeeeee;
position: relative;
}
.progress.thin {
margin-top: 0.9rem;
height: 0.4rem;
}
.progress.thin .progress-label {
margin-top: -0.4rem;
}
.progress.thin .progress-bar {
height: 0.4rem;
}
.progress.candystripe .progress-bar {
background-image: linear-gradient(135deg, var(--md-progress-stripe) 27%, transparent 27%, transparent 52%, var(--md-progress-stripe) 52%, var(--md-progress-stripe) 77%, transparent 77%, transparent);
background-size: px2rem(40px) px2rem(40px);
}
.progress.static.lightcyan .progress-bar {
background-color:hsl(187deg 91% 47%);
}
.progress.static.blue .progress-bar {
background-color:#2979ff;
}
.progress.static.verydarkcyan .progress-bar {
background-color:hsl(187deg 39% 22%);
}
.progress.static.darkcyan .progress-bar {
background-color:darkcyan;
}
.progress.static.blueviolet .progress-bar {
background-color:blueviolet;
}
.progress.static.bisque .progress-bar {
background-color:bisque;
}
.progress.static.darkgreen .progress-bar {
background-color:darkgreen;
}
.progress.static.green .progress-bar {
background-color:green;
}
.progress.static.orange .progress-bar {
background-color:orange;
}
.progress.static.orangered .progress-bar {
background-color:orangered;
}
.progress.static.olivedrab .progress-bar {
background-color:olivedrab;
}
.progress.static.red .progress-bar {
background-color:red;
}
.progress.static.gray .progress-bar {
background-color:gray;
}
.progress.static.grey .progress-bar {
background-color: hsl(0deg 5% 89%);
}
.progress-100plus .progress-bar {
background-color: #00e676;
}
.progress-80plus .progress-bar {
background-color: #fbc02d;
}
.progress-60plus .progress-bar {
background-color: #ff9100;
}
.progress-40plus .progress-bar {
background-color: #ff5252;
}
.progress-20plus .progress-bar {
background-color: #ff1744;
}
.progress-0plus .progress-bar {
background-color: #f50057;
}
@keyframes animate-stripes {
0% {
background-position: 0 0;
}
100% {
background-position: px2rem(120px) 0;
}
}
Lets add theme/partials/footer.html
{#-
This file is required to override the default MkDocs footer - do not edit
-#}
{% import "partials/language.html" as lang with context %}
<footer class="md-footer">
{% if page.previous_page or page.next_page %}
<div class="md-footer-nav">
<nav class="md-footer-nav__inner md-grid">
{% if page.previous_page %}
<a href="{{ page.previous_page.url | url }}" title="{{ page.previous_page.title | striptags }}" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
<div class="md-flex__cell md-flex__cell--shrink">
<i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
</div>
<div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
<span class="md-flex__ellipsis">
<span class="md-footer-nav__direction">
{{ lang.t("footer.previous") }}
</span>
{{ page.previous_page.title }}
</span>
</div>
</a>
{% endif %}
{% if page.next_page %}
<a href="{{ page.next_page.url | url }}" title="{{ page.next_page.title | striptags }}" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
<div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
<span class="md-flex__ellipsis">
<span class="md-footer-nav__direction">
{{ lang.t("footer.next") }}
</span>
{{ page.next_page.title }}
</span>
</div>
<div class="md-flex__cell md-flex__cell--shrink">
<i class="md-icon md-icon--arrow-forward md-footer-nav__button"></i>
</div>
</a>
{% endif %}
</nav>
</div>
{% endif %}
</footer>
Lets update the mkdocs.yml as follows
site_name: 'doc-as-code'
nav:
- Home: index.md
repo_name: 'github/doc-as-code'
repo_url: 'https://github.com/mnadeem/doc-as-code'
edit_uri: 'blob/master/docs'
copyright: 'Copyright © 2020 App'
theme:
name: material
palette:
primary: 'green'
accent: 'green'
# feature:
# tabs: true
custom_dir: 'theme'
#favicon: img/favicon.ico
#logo: img/logo.png
icon:
logo: material/file-document
font:
text: Arial
code: Roboto Mono
extra:
social:
- type: 'github'
link: 'https://github.com/mnadeem'
icon: fontawesome/brands/github-alt
extra_css:
- styles/app-theme.css
- https://unpkg.com/[email protected] /dist/mermaid.css
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
- javascripts/tables.js
- https://unpkg.com/[email protected] /dist/mermaid.min.js
markdown_extensions:
- meta
- toc:
permalink: true
- admonition
- footnotes
- pymdownx.arithmatex
- pymdownx.betterem:
smart_enable: all
- pymdownx.caret
- attr_list
- pymdownx.critic
- pymdownx.details
- pymdownx.inlinehilite
- pymdownx.magiclink
- pymdownx.mark
- pymdownx.smartsymbols
- pymdownx.highlight
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_div_format
- pymdownx.tabbed
- def_list
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.tilde
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
- pymdownx.snippets
- pymdownx.progressbar
- codehilite:
linenums: true
E:\mkdocs\doc-as-code>mkdocs gh-deploy --force
INFO - Cleaning site directory
INFO - Building documentation to directory: E:\mkdocs\doc-as-code\site
INFO - Documentation built in 1.44 seconds
INFO - Copying 'E:\mkdocs\doc-as-code\site' to 'gh-pages' branch and pushing to GitHub.
INFO - Your documentation should shortly be available at: https://mnadeem.github.io/doc-as-code/
Add more pages
Add more navigations
nav:
- Home: index.md
- Getting Started:
- Document As Code: getting-started/document-as-code.md
- Creating Pages: getting-started/creating-pages.md
- Creating Diagrams: getting-started/creating-diagrams.md
References
Craftsman Nadeem 