Skip to content

Docs🔗

Using an Alpine template to keep it as resource-efficient as possible:
Alpine basic setup

Alpine setup

Väga lühike info killuke selle kohta kuidas ma Alpine LXC püsti panen.
Ei kasuta Template kuna ei tea mida läheb vaja ja mida mitte.

Basic setup
Vaikimisi on vale timezone, panen eesti:
apk update
apk add tzdata
ln -sf /usr/share/zoneinfo/Europe/Tallinn /etc/localtime

apk update
apk upgrade

VS Code sõltuvuspaketid + SSH
SSH jaoks kasutan Dropbear kuna see on väidetavalt rohkem light weight ja ma ei pea eraldi lubama root kontol SSH kasutamist (jah ma tean, et ma ei võiks root kontot kasutada)
apk add gcompat libstdc++ bash grep wget tar curl openrc dropbear
rc-service dropbear start
rc-update add dropbear

Docker ja Compose
Install: apk add --update docker docker-compose
Peale installi on vaja ka boot startup lisada:
rc-update add docker boot
service docker start
service docker status

Background info - I am using MkDocs, specifically the Properdocs version, because the creators of MkDocs are working on version 2.0, which is completely new software and doesn't support anything from the old version:
The Material creators' blog - What MkDocs 2.0 means for your documentation projects

In the future, once Zensical supports multi-language functionality, I will migrate over to it.

Addisionally, files are in GitHub and I use Cloudflare Pages to run the page, this LXC is for internal testing before I do a 'git push'.

Configuration🔗

The setup is otherwise very simple; the only thing is adding the desired features to the config file and then writing the md files.

Plugins🔗

Some plugins are required, otherwise nothing will work:
pip install properdocs>=1.6.7 mkdocs-material>=9.7.6
And the others are extras that I use:
pip install mkdocs-glightbox>=0.5.2 mkdocs-literate-nav>=0.6.3 mkdocs-include-markdown-plugin>=7.3.0 mkdocs-video>=1.5.0 mkdocs-d2-plugin>=1.7.0 mkdocs-static-i18n>=1.3.1 mkdocs-git-revision-date-localized-plugin>=1.5.3 mkdocs-minify-plugin>=0.8.0

My config: I've cut out a few things here just to make it more readable.

mkdocs.yml file 
site_name: Timmo homelab
site_url: https://docs.timmo.ee/
use_directory_urls: true

extra_javascript:
  - assets/javascripts/logos-mermaid.js

extra_css:
  - assets/stylesheets/theme.css

extra:
  alternate:
    - name: Eesti
      link: /
      lang: et
    - name: English
      link: /en/
      lang: en

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.snippets:
      base_path: docs
  - pymdownx.betterem
  - pymdownx.blocks.caption
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.superfences
#      custom_fences:
#        - name: mermaid
#          class: mermaid
#          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - sane_lists
  - tables
  - toc:
      permalink: 🔗

theme:
  language: et
  name: material
  custom_dir: docs/overrides
  logo: assets/images/logo.png
  favicon: assets/images/logo.png
  features:
    - content.footnote.tooltips
    - content.code.copy
    - content.code.select
    - content.code.annotate
    - navigation.instant
    - navigation.instant.progress
    - navigation.instant.prefetch
    - search.suggest
    - search.highlight
    - search.share
    - navigation.top
    - navigation.tabs
    - navigation.path
    - navigation.expand
    - navigation.indexes
    - mermaid
    - content.tabs.link
  font: false
  palette:
    # Light Mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/lightbulb-outline
        name: Switch to light mode
#      primary: indigo
#      accent: deep purple
    # Dark Mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/lightbulb
        name: Switch to dark mode
      primary: black
#      accent: deep purple

nav:
  - Home: et/index.md

plugins:
  - include-markdown
  - glightbox:
      touchNavigation: true
      loop: false
      effect: zoom
#      width: 100%
      height: auto
      zoomable: true
      draggable: true
      auto_caption: false
      caption_position: bottom
  - d2:
      cache: false
      layout: elk
      theme: 101
      dark_theme: 200
      scale: 1.0
      pad: 25
#  - kroki:
#      tag_format: svg
  - i18n:
      docs_structure: folder
      fallback_to_default: false
      reconfigure_material: true
      reconfigure_search: true
      languages:
        - locale: et
          name: Estonian
          default: true
          build: true
        - locale: en
          name: English
          build: true
          nav:
            - Homepage: index.md
  - git-revision-date-localized:
      enable_creation_date: true
  - search
  - minify:
      minify_html: true

Testing
For testing, you need python + venv, and inside that venv, you run the command for the live environment.

Python install: apk add python3
Creating a venv: python -m venv FOLDER_NAME
Entering the virtual environment: source FOLDER_NAME/bin/activate
Installing packages: pip install PACKAGE_NAMES
Test: properdocs serve -f path/to/file/mkdocs.yml -a 0.0.0.0:8000
You can use whatever filename you want, it doesn't have to be mkdocs.yml if you use the '-f' parameter, but without it, the command looks for a file named mkdocs.yml in the same folder.