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

• creating a home page
• background svg
• site I used for background svg
• setting up the footer

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

{% 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="false"
    src="https://isso.vectorspace.xyz/js/embed.min.js">
  </script>
{% endif %}
<section id="isso-thread"></section>

Since we will be using our own css, you can set data-isso-css to "false".

/* ========================================================================== */
/* Generic styling                                                            */
/* ========================================================================== */
#isso-thread * {
    /* Reset */
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
}
/* ========================================================================== */
/* Thread heading area                                                        */
/* ========================================================================== */
#isso-thread {
    padding: 0;
    margin: 0;
}
h4.isso-thread-heading {
    color: var(--md-default-fg-color--light, #555);
    font-weight: bold;
}
.isso-feedlink {
    float: right;
    padding-left: 1em;
}
.isso-feedlink a {
    font-size: 0.8em;
    vertical-align: bottom;
    color: var(--md-accent-fg-color, #1976d2);
    text-decoration: none;
}
.isso-feedlink a:hover {
    color: var(--md-accent-fg-color--transparent, rgba(25, 118, 210, 0.8));
}
/* ========================================================================== */
/* Comments                                                                   */
/* ========================================================================== */
.isso-comment {
    max-width: 68em;
    margin: 0 auto;
    background-color: var(--md-default-bg-color, #fff);
    color: var(--md-default-fg-color, #000);
}
.isso-preview .isso-comment {
    padding-top: 0;
    margin: 0;
}
.isso-comment:not(:first-of-type),
.isso-follow-up .isso-comment {
    border-top: 1px solid var(--md-default-fg-color--lightest, rgba(0, 0, 0, 0.1));
    margin-bottom: 0.5em;
}
.isso-avatar {
    display: block;
    float: left;
    margin: 0.95em 0.95em 0;
}
.isso-avatar svg {
    max-width: 48px;
    max-height: 48px;
    width: 100%;
    height: 100%;
    border: 1px solid var(--md-default-fg-color--lightest, rgba(0, 0, 0, 0.2));
    border-radius: 3px;
    box-shadow: 0 1px 2px var(--md-shadow-z1, rgba(0, 0, 0, 0.1));
}
.isso-text-wrapper {
    display: block;
    padding: 0.95em;
}
.isso-follow-up {
    padding-left: calc(7% + 20px);
}
.isso-comment-footer {
    font-size: 0.95em;
}
.isso-comment-header {
    font-size: 0.85em;
}
.isso-comment-header a {
    text-decoration: none;
    color: var(--md-accent-fg-color, #1976d2);
}
.isso-comment-header a:hover {
    color: var(--md-accent-fg-color--transparent, rgba(25, 118, 210, 0.8));
}
/* Only for comment header, spacer between up-/downvote should have no padding */
.isso-comment-header .isso-spacer {
    padding: 0 6px;
}
.isso-spacer,
.isso-permalink,
.isso-note,
.isso-parent {
    color: var(--md-default-fg-color--light, gray);
    font-weight: normal;
    text-shadow: none;
}
.isso-spacer:hover,
.isso-permalink:hover,
.isso-note:hover,
.isso-parent:hover {
    color: var(--md-default-fg-color, #606060);
}
.isso-note {
    float: right;
}
.isso-author {
    font-weight: bold;
    color: var(--md-default-fg-color--light, #555);
}
.isso-page-author-suffix {
    font-weight: bold;
    color: var(--md-default-fg-color, #2c2c2c);
}
.isso-textarea,
.isso-preview {
    margin-top: 0.2em;
    width: 100%;
    border: 1px solid var(--md-default-fg-color--lightest, #f0f0f0);
    border-radius: 2px;
    box-shadow: 0 0 2px var(--md-shadow-z1, rgba(0, 0, 0, 0.2));
    background-color: var(--md-default-bg-color, #fff);
    color: var(--md-default-fg-color, #000);
}
.isso-text p {
    margin-top: 0.2em;
}
.isso-text p:last-child {
    margin-bottom: 0.2em;
}
.isso-text h1,
.isso-text h2,
.isso-text h3,
.isso-text h4,
.isso-text h5,
.isso-text h6 {
    font-size: 130%;
    font-weight: bold;
    color: var(--md-default-fg-color, #000);
}
.isso-text a {
    color: var(--md-accent-fg-color, #1976d2);
    text-decoration: none;
}
.isso-text a:hover {
    color: var(--md-accent-fg-color--transparent, rgba(25, 118, 210, 0.8));
    text-decoration: underline;
}
.isso-comment-footer {
    font-size: 0.80em;
    color: var(--md-default-fg-color--light, gray);
    clear: left;
}
.isso-feedlink,
.isso-comment-footer a {
    font-weight: bold;
    text-decoration: none;
    color: var(--md-accent-fg-color, #1976d2);
}
.isso-feedlink:hover,
.isso-comment-footer a:hover {
    color: var(--md-default-fg-color, #111111);
    text-shadow: var(--md-default-fg-color--lightest, #aaaaaa) 0 0 1px;
}
.isso-comment-footer > a {
    position: relative;
    top: .2em;
}
.isso-comment-footer > a + a {
    padding-left: 1em;
}
.isso-comment-footer .isso-votes {
    color: var(--md-default-fg-color--light, gray);
}
.isso-upvote svg,
.isso-downvote svg {
    position: relative;
    top: .2em;
    fill: var(--md-default-fg-color--light, gray);
}
.isso-upvote:hover svg,
.isso-downvote:hover svg {
    fill: var(--md-accent-fg-color, #1976d2);
}
/* Reply postbox under existing comment */
.isso-comment .isso-postbox {
    margin-top: 0.8em;
}
.isso-comment.isso-no-votes > * > .isso-comment-footer .isso-votes {
    display: none;
}
/* ========================================================================== */
/* Postbox                                                                    */
/* ========================================================================== */
.isso-postbox {
    max-width: 68em;
    margin: 0 auto 2em;
    clear: right;
}
.isso-form-wrapper {
    display: block;
    padding: 0;
}
.isso-textarea,
.isso-preview {
    margin: 0 0 .3em;
    padding: .4em .8em;
    border-radius: 3px;
    background-color: var(--md-default-bg-color, #fff);
    border: 1px solid var(--md-default-fg-color--lightest, rgba(0, 0, 0, 0.2));
    box-shadow: 0 1px 2px var(--md-shadow-z1, rgba(0, 0, 0, 0.1));
    color: var(--md-default-fg-color, #000);
}
.isso-textarea {
    outline: 0;
    width: 100%;
    resize: none;
}
.isso-textarea::placeholder {
    color: var(--md-default-fg-color--light, #666);
}
.isso-form-wrapper input[type=checkbox] {
    vertical-align: middle;
    position: relative;
    bottom: 1px;
    margin-left: 0;
    accent-color: var(--md-accent-fg-color, #1976d2);
}
.isso-notification-section {
    font-size: 0.90em;
    padding-top: .3em;
    display: none;
    padding-bottom: 10px;
    color: var(--md-default-fg-color, #000);
}
.isso-auth-section {
    display: block;
}
.isso-textarea:focus,
.isso-auth-section input:focus {
    border-color: var(--md-accent-fg-color, rgba(25, 118, 210, 0.8));
    outline: 2px solid var(--md-accent-fg-color--transparent, rgba(25, 118, 210, 0.2));
    outline-offset: -1px;
}
.isso-input-wrapper {
    display: inline-block;
    position: relative;
    max-width: 25%;
    margin: 0;
}
.isso-input-wrapper input {
    padding: .3em 10px;
    max-width: 100%;
    border-radius: 3px;
    background-color: var(--md-default-bg-color, #fff);
    line-height: 1.4em;
    border: 1px solid var(--md-default-fg-color--lightest, rgba(0, 0, 0, 0.2));
    box-shadow: 0 1px 2px var(--md-shadow-z1, rgba(0, 0, 0, 0.1));
    color: var(--md-default-fg-color, #000);
}
.isso-input-wrapper input::placeholder {
    color: var(--md-default-fg-color--light, #666);
}
.isso-input-wrapper label {
    display: inline-block;
    line-height: 1.4em;
    height: 1.4em;
    color: var(--md-default-fg-color, #000);
}
.isso-post-action {
    display: block;
    float: right;
    margin: 1.4em 0 0 5px;
}
.isso-post-action > input {
    padding: calc(.3em - 1px);
    border-radius: 2px;
    border: 1px solid var(--md-default-fg-color--lighter, #ccc);
    background-color: var(--md-default-bg-color--light, #ddd);
    cursor: pointer;
    outline: 0;
    line-height: 1.4em;
    box-shadow: 0 1px 2px var(--md-shadow-z1, rgba(0, 0, 0, 0.1));
    color: var(--md-default-fg-color, #000);
}
.isso-post-action > input:hover {
    background-color: var(--md-default-fg-color--lightest, #ccc);
}
.isso-post-action > input:active {
    background-color: var(--md-default-fg-color--lighter, #bbb);
}
.isso-post-action > input:focus {
    outline: 2px solid var(--md-accent-fg-color, #1976d2);
    outline-offset: 2px;
}
/* ========================================================================== */
/* Postbox (preview mode)                                                     */
/* ========================================================================== */
.isso-preview,
.isso-post-action input[name="edit"],
.isso-postbox.isso-preview-mode > .isso-form-wrapper input[name="preview"],
.isso-postbox.isso-preview-mode > .isso-form-wrapper .isso-textarea {
    display: none;
}
.isso-postbox.isso-preview-mode > .isso-form-wrapper .isso-preview {
    display: block;
}
.isso-postbox.isso-preview-mode > .isso-form-wrapper input[name="edit"] {
    display: inline;
}
.isso-preview {
    background-color: var(--md-code-bg-color, #f8f8f8);
    background: repeating-linear-gradient(
        -45deg,
        var(--md-code-bg-color, #f8f8f8),
        var(--md-code-bg-color, #f8f8f8) 10px,
        var(--md-default-bg-color, #fff) 10px,
        var(--md-default-bg-color, #fff) 20px
    );
}
/* ========================================================================== */
/* Animations                                                                 */
/* ========================================================================== */
/* "target" means the comment that's being linked to, for example:
 * https://example.com/blog/example/#isso-15
 */
.isso-target {
    animation: isso-target-fade 5s ease-out;
}
@keyframes isso-target-fade {
    0% { 
        background-color: var(--md-accent-fg-color--transparent, #eee5a1);
    }
    /* Automatically adapts to light/dark theme */
}
/* ========================================================================== */
/* Dark theme specific adjustments                                            */
/* ========================================================================== */
/* These rules will automatically apply when MkDocs Material switches to dark theme */
[data-md-color-scheme="slate"] .isso-textarea,
[data-md-color-scheme="slate"] .isso-preview,
[data-md-color-scheme="slate"] .isso-input-wrapper input {
    background-color: var(--md-default-bg-color);
    color: var(--md-default-fg-color);
    border-color: var(--md-default-fg-color--lightest);
}

[data-md-color-scheme="slate"] .isso-post-action > input {
    background-color: var(--md-default-fg-color--lightest);
    color: var(--md-default-fg-color);
    border-color: var(--md-default-fg-color--lighter);
}

[data-md-color-scheme="slate"] .isso-post-action > input:hover {
    background-color: var(--md-default-fg-color--lighter);
}
/* ========================================================================== */
/* Media queries                                                              */
/* ========================================================================== */
@media screen and (max-width:600px) {
    .isso-input-wrapper {
        display: block;
        max-width: 100%;
        margin: 0 0 .3em;
    }
    .isso-input-wrapper input {
        width: 100%;
    }
    .isso-post-action {
        margin-top: 0;
    }
}

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