Welcome to MkDocs

Commands

• mkdocs new [dir-name] - Create a new project.
• mkdocs serve - Start the live-reloading docs server.
• mkdocs build - Build the documentation site.
• mkdocs -h - Print help message and exit.

Project layout

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.

Documentation

• mkdocs
• Material for MkDocs
  • Getting started
  • Setup
  • Reference
  • PyMdown Extensions(built-in into Material for MkDocs)

• Plugins:

  • List of plugins from official mkdocs github repo
  • The best MkDocs plugins and customizations(medium)
  • mkdocs-awesome-pages-plugin
  • mkdocs-exclude
  • mkdocs-video
  • mkdocs-macros-plugin

• Style:

  • Code syntax highlight:

    1. Code blocks: Custom syntax theme(docs)
    2. Source style sheet(_colors.scss)
    3. Syntax theme definition(_highlight.scss)

  • Icons + Emojis Search

    • - :fontawesome-brands-youtube:
    • - :material-thumb-up:
    • - :material-thumb-down:
    • - :fontawesome-solid-file-excel:
    • - :fontawesome-regular-file-excel:
    • - :fontawesome-solid-file-word:
    • - :fontawesome-regular-file-word:
    • - :fontawesome-solid-file-powerpoint:
    • - :fontawesome-regular-file-powerpoint:
    • - :material-web:
    • - :octicons-logo-github-16:
    • - :octicons-mark-github-16:
    • - :fontawesome-brands-github:
    • - :material-github:
    • - :material-arch:
    • - :simple-mdnwebdocs:
    • - :fontawesome-brands-medium:
    • - :simple-medium:
    • - :simple-digitalocean:
    • - :fontawesome-brands-digital-ocean:
    • - :material-digital-ocean:

• Personal customization to implement in the future:

  • medium-zoom, medium-zoom docsify plugin

• How To:

  • Embed image with captions

    <figure markdown>
      ![Javascript Engine](image-file){: .zoom}
      <figcaption>
          <a href="image-source-link" target="_blank">image-caption(e.g. image-source-description)</a>
      </figcaption>
    </figure>
    

  • Embed video: MkDocs Video plugin, 1, 2

  • Embed YouTube Video List

    copy initial embed code from the YouTube and then set width="400vw" height="225vw"

    <iframe width="400vw" height="225vw" src="https://www.youtube.com/embed/gb7gMluAeao?list=PLcvhF2Wqh7DNVy1OCUpG3i5lyxyBWhGZ8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
    

  • Embed pdf:

    1. Embedding a PDF file

       <object data="../foo.pdf" type="application/pdf" class="pdf"></object>
       

    2. Creating a link to a PDF file

       <a href="../foo.pdf" class="image fit" style="color: red">:fontawesome-regular-file-pdf:</a>
       

       or

       <a href="../foo.pdf" class="image fit" style="color: red">:fontawesome-solid-file-pdf:</a>
       

    3. docsify-pdf-embed.js

---

Last update: 2023-01-26