Skip to content

Markdown Documentation Guidelines

Context: This directory contains all project documentation in Markdown format.

Specific Instructions for Markdown Files: - Use clear and descriptive headings (H1 for main topic, H2 for sub-sections). - Employ bullet points and numbered lists for readability. - Use backticks (`) for inline code and triple backticks () for code blocks, specifying the language (e.g.,bash, ```python). - Keep paragraphs concise. - Link to relevant files or sections using relative paths where appropriate. - Ensure a consistent tone and voice (e.g., formal, informal, instructional). - Favor simple Markdown over complex HTML embeds unless absolutely necessary. - All documentation is written in Markdown and generated using the MkDocs with the Material theme. - Adhere strictly to the MkDocs-Material syntax extensions for features like admonitions, content tabs, and icons. - Ensure all new pages are added to the nav section of the mkdocs.yml file to appear in the site navigation. - All internal links must be relative and point to other .md files within the docs/ directory. - Do not use first-person nor third-person perspective in the document.

Markdown Style Guide:

  • Headings: Use ATX-style headings (#, ##, ###, etc.). The main page title is always H1 (#).
  • All Headings should start with emoji using mkdocs-material compatible shortcode.
  • Admonitions: Use admonitions to highlight important information.
  • !!! note for general information.
  • !!! code for computer code and commands.
  • !!! abstract for referencing files.
  • ??? abstract for long files that need to be collapsed.
  • !!! tip for helpful advice.
  • !!! warning for critical warnings or potential issues.
  • !!! danger for severe risks.
  • Code Blocks: Always specify the language for syntax highlighting (e.g., ```python). For shell commands, use shell or bash. Use ini for .env files.
  • Lists: Use hyphens (-) for unordered lists and numbers (1.) for ordered lists.
  • Icons & Emojis: Use Material Design icons and emojis where appropriate to improve visual communication, e.g., :material-check-circle: for success.
  • Icons & Emojis: Use the short codes for emoji instead of the emoji itself.
  • Use 2 spaces for indentation.
  • List items that are links should be inclosed with < and >.
  • Formatting shall be compatible with markdownlint.
  • All hyperlinks should reference a number and the numbers should be at the bottom of the document (e.g. [tool name][1] and1: ` )

Sections:

  • All sections should have emoji in front of the section name.
  • References: Always end a page with a References section.
  • References section starts with the 🔗 emoji.
  • References section has a list of relevant links.
  • Config: Create a config section
  • Installation: Create an installation section.
  • This section should show instructions for both amd64 and arm64 architectures.
  • Usage: Create a usage section

docs/apps/

  • This directory contains apps that are installed in my homelab.
  • Instructions should be given for installing the app.

docs/tools/

  • This directory contains tools that are used in my homelab.

Regarding Dependencies:

  • The primary dependency is mkdocs-material.
  • The project also uses the pymdown-extensions for advanced formatting.
  • Mermaid is an acceptable plugin.
  • Do not introduce new MkDocs plugins without prior discussion and approval.

Example Script Structure:

tags: - relevant-tags

:emoji: Name of application or tool

Description of application or tool. The name of the tool should be a hyperlink to the original source.

🛠 Installation

Instructions on how to install the application or tool.

code to install the application or tool

code to install the application or tool

⚙ Config

Instructions on how to configure the application or tool.

homelab/path/config/file

example of yaml config file

📝 Usage

Instructions on how to use the application or tool.

🚀 Upgrade

Code to upgrade the application or tool.

task update

command to update application or tool

🔗 References