Skip to content

mkdocs-material

installation (on archlinux)

sudo pacman -S mkdocs-material python-pymdown-extensions

Also install python-paginate.

python-paginate PKGBUILD
pkgname=python-paginate
pkgver=0.1
pkgrel=1
pkgdesc='This module helps dividing large lists of items into pages. '
arch=('any')
url='https://github.com/Pylons/paginate'
license=('MIT')
depends=('python' 'python-click')
makedepends=('python-setuptools-scm' 'python-wheel' 'python-installer' 'python-build')
source=("${pkgname}.zip"::"https://github.com/Pylons/paginate/archive/refs/heads/master.zip")
sha256sums=('SKIP')

build() {
  cd "paginate-master"
  python -m build --wheel --no-isolation
}

package() {
  cd "paginate-master"
  python -m installer --destdir="$pkgdir" dist/*.whl
  install -Dvm644 'README.md' -t "${pkgdir}/usr/share/doc/${pkgname}"
  install -Dvm644 'LICENSE' -t "${pkgdir}/usr/share/licenses/${pkgname}"
}

I don't use this plugin. Just mentioning this here cause I made its PKGBUILD.

mkdocs-awesome-pages-plugin PKGBUILD
pkgname=python-mkdocs-awesome-pages
pkgver=0.1
pkgrel=1
pkgdesc='An MkDocs plugin that simplifies configuring page titles and their order'
arch=('any')
url='https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin'
license=('MIT')
depends=('python' 'mkdocs' 'python-wcmatch' 'python-natsort')
makedepends=('python-setuptools-scm' 'python-wheel' 'python-installer' 'python-build')
source=("${pkgname}.zip"::"https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/archive/refs/heads/master.zip")
sha256sums=('SKIP')

build() {
  cd "mkdocs-awesome-pages-plugin-master"
  python -m build --wheel --no-isolation
}

package() {
  cd "mkdocs-awesome-pages-plugin-master"
  python -m installer --destdir="$pkgdir" dist/*.whl
  install -Dvm644 'README.md' -t "${pkgdir}/usr/share/doc/${pkgname}"
  install -Dvm644 'LICENSE.md' -t "${pkgdir}/usr/share/licenses/${pkgname}"
}

adding title to codeblocks

source: https://squidfunk.github.io/mkdocs-material/reference/code-blocks/

```title="/etc/kernel/cmdline"
rd.luks.name=e789d34e-224b-49f6-be22-87f08131e3ad=root root=/dev/mapper/root rw ps1=1
```

results in ...

/etc/kernel/cmdline
rd.luks.name=e789d34e-224b-49f6-be22-87f08131e3ad=root root=/dev/mapper/root rw ps1=1<br>

creating a home page

basics

writing your docs

raw html

You can paste raw html into the site like this:

<figure class="video_container">
  <video controls="true" allowfullscreen="true">
    <source src="../res/out.mp4" type="video/mp4">
  </video>
</figure>

Made use of this in ffmpeg.

source: https://github.com/squidfunk/mkdocs-material/discussions/3984#discussioncomment-6374978

Add isso to mkdocs-material:

For more info check out isso

docs/overrides/partials/comments.html
{% if page and page.meta and page.meta.isso is boolean %}
  {% set isso = page.meta.isso %}
{% else %}
  {% set isso = true %}
{% endif %}

{% if not page.is_homepage and isso %}
  <!-- replace disqus with isso -->
  <br>
  <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
  <div id="disqus_thread"></div>
  <script
    data-isso="https://isso.vectorspace.xyz/"
    data-isso-css="true"
    data-isso-require-author="true"
    data-isso-require-email="true"
    data-isso-reply-to-self="false"
    src="https://isso.vectorspace.xyz/js/embed.min.js">
  </script>
{% endif %}
<section id="isso-thread"></section>

systemd service

~/bin/mkdocs-server.sh
#!/bin/bash

cd /home/vector/vectorspacexyz.github.io
mkdocs serve
~/.config/systemd/user/mkdocs-server.service
[Unit]
Description=Start the mkdocs server

[Service]
ExecStart='/home/vector/bin/mkdocs-server.sh'

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user start mkdocs-server.service
systemctl --user enable mkdocs-server.service

extensions

Add the following to extensions mkdocs.yml:

https://squidfunk.github.io/mkdocs-material/reference/code-blocks/

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

write, don't publish yet (drafts)

---
title: Some title
draft: true
date: 2024-10-24
---

Set font and code font size

mkdocs.yml
site_name: vectorspace.xyz
theme:
  name: material
  custom_dir: overrides
  favicon: img/Tux.png
  font:
    text: Ubuntu
    code: Ubuntu Mono
extra_css:
  - stylesheets/extra.css
...
docs/stylesheets/extra.css
.md-typeset code {
  font-size: 18px;  /* Adjust this value as needed */
}

Hiding toc, navigation and comments

source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#hiding-the-sidebars-hide-both

This proved to be very useful for my tech index page which uses grids as I was spared the trouble of creating a separate template just for index pages.

---
title: index
isso: false
hide:
  - navigation
  - toc
---

<div class="grid cards" markdown>
- [arch linux](arch.md)
- [archive.org](archive.md)
- [bash](bash.md)
- [bitwarden](bitwarden.md)
- [bluetoothctl](bluetoothctl.md)
- [chromium](chromium.md)
- [cryptsetup](cryptsetup.md)
- ...
</div>

Comments