Basics

To create and serve a mkdocs site

mkdocs new sample_site
cd sampe_site
# Default port 8000, to use 8001 instead
mkdocs serve -a 127.0.0.1:8001

By default site will be served at 127.0.0.1:8000/

Structure

sameple_site $ ls
docs  mkdocs.yml

docs is the root of your website. If you place the website logo in docs/assets/logo.png, you can access it at 127.0.0.1:8000/assets/logo.png. the index.md file becomes your home page.

mkdocs.yml is the main file through while you will configure your mkdocs site.

To set the theme to material:

mkdocs.yml

site_name: My Docs
theme:
  name: material

Customization

source: https://squidfunk.github.io/mkdocs-material/customization/

Extras (Not ordered)

main tweak steps

# Full clean build
npm run clean
npm run build

# Test your changes
mkdocs serve

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