Skip to content

index

creating a mkdocs site

source: https://www.mkdocs.org/getting-started/ 

mkdocs new my-project
cd my-project

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>

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