Skip to main content

TechDocs Best Practices

Introduction​

TechDocs is IDP’s documentation site generator, leveraging MkDocs to convert Markdown files into a static site adhering to the concepts of docs-like-code. This guide highlights best practices for creating and maintaining documentation in TechDocs, including generating one-page and multi-page sites, using MkDocs plugins, embedding videos, and creating architecture diagrams.

Creating a One-Page Docs Site​

One-page documentation is ideal for quick-start guides, FAQs, or any standalone documentation.

Steps:​

  1. Set Up the Directory:
  • Create a docs folder in your repository and add a single README.md file inside it. Add your documentation content directly to README.md. GitHub and TechDocs both recognize and render it automatically.
  1. Serve in IDP:
  • Ensure the repository is registered in your catalog-info.yaml file. TechDocs will automatically render the content without additional setup.

Working with Multi-Page Sites​

For projects requiring detailed documentation, multi-page sites are recommended. These sites can have hierarchical navigation and allow for better content organization.

Auto-Generated Navigation​

MkDocs can automatically generate navigation based on folder and file structures.

  • Example Structure:
/docs
  |-- index.md
  |-- guide/
       |-- getting-started.md
       |-- troubleshooting.md
  |-- reference/
       |-- api.md

  • Resulting Navigation (Auto-Generated):

    • Home
    • Guide
      • Getting Started
      • Troubleshooting
    • Reference
      • API
info

Even with auto-generated navigation, you can include an mkdocs.yml file. In this case, you cannot define a nav section for custom navigation, but you can still specify other configurations like site_name and plugins.

  • Example mkdocs.yml for Auto-Generated Navigation:
site_name: Project Documentation
plugins:
  - techdocs-core

If no mkdocs.yml file is present, TechDocs will automatically create a basic configuration during rendering.

Manual Navigation Control​

For custom navigation, explicitly define the structure in a mkdocs.yml file by adding a nav section.

  • Example mkdocs.yml for Manual Navigation:
site_name: Project Documentation
plugins:
  - techdocs-core
nav:
  - Home: index.md
  - Guide:
      - Getting Started: guide/getting-started.md
      - Troubleshooting: guide/troubleshooting.md
  - Reference:
      - API: reference/api.md
info

Always include the techdocs-core plugin for compatibility with TechDocs.

Here's an example mkdocs.yml following the above structure.

Here's a video tutorial explaining the same

Enhancing Docs with Architecture Diagrams​

Visual representations, such as architecture diagrams, improve documentation clarity. Use the installed MkDocs plugins for diagrams.

Adding an Architecture Diagram (PNG)​

  1. Store Your Diagram in the same repo as mkdocs.yml

Save your architecture diagram in the docs folder or a subdirectory, such as docs/static. Only images stored in these locations will render correctly in TechDocs.

Example Structure:

Copy code
/docs
  |-- index.md
  |-- static/
       |-- architecture-diagram.png
  1. Reference the Diagram in Markdown
  • Use Markdown syntax to embed the diagram in your documentation:
![Architecture Diagram](static/architecture-diagram.png)
  1. Ensure Proper Rendering
  • The relative path (static/architecture-diagram.png) should match the diagram's location within the docs directory. For instance:

If the image is at /docs/static/architecture-diagram.png, reference it as static/architecture-diagram.png. If the image is at /docs/architecture-diagram.png, reference it as architecture-diagram.png.

Add Diagrams as code​

1. Using Mermaid for Diagrams​

Mermaid diagrams are supported out of the box.

### System Architecture Diagram

```mermaid
graph TD;
    A[Client] -->|Requests| B[Backend API];
    B -->|Responses| C[Database];
    C -->|Data| B;

Supported Diagram Types:​

  • Flowcharts
  • Sequence Diagrams
  • Gantt Charts
  • Pie Charts

For more syntax options, refer to the Mermaid documentation.

Instructions to use in local environment:​

  • Ensure the mkdocs-mermaid2-plugin is installed and configured in your mkdocs.yml.
plugins:
    - mermaid2

For more information refer here

2. Using PlantUML for Advanced Diagrams​

PlantUML is ideal for more detailed and customizable diagrams, such as class diagrams, activity diagrams, and deployment diagrams.

Example Usage:​

  • In your Markdown file:
### Deployment Diagram

```plantuml
@startuml
actor User
participant "Frontend" as FE
participant "Backend" as BE
database "Database" as DB

User -> FE : Request
FE -> BE : Process Request
BE -> DB : Query Data
DB --> BE : Return Data
BE --> FE : Response
FE --> User : Render Data
@enduml

Instructions to use in local environment:​

  • PlantUML is available as part of the techdocs-core plugin.
plugins:
    - techdocs-core

For more information refer here

3. Using Graphviz diagrams​

Allows inline rendering of Graphviz diagrams (DOT language) directly in Markdown files.

Example Usage

# Inline Graphviz Diagram

```graphviz
digraph G {
    A -> B;
    B -> C;
    C -> A;
}

Instructions to use in local environment:​

  • Graphviz is available as part of the techdocs-core plugin.
plugins:
    - techdocs-core

For more information refer here

Embedding Videos in TechDocs​

Embedding videos enriches documentation, especially for tutorials or product demonstrations.

Embedding Videos Using iframe​

To embed videos hosted on platforms like YouTube or Vimeo, use the following syntax:

<iframe 
  width="560" 
  height="315" 
  src="https://www.youtube.com/embed/VIDEO_ID" 
  title="Video title" 
  frameborder="0" 
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" 
  allowfullscreen>
</iframe>
  • Replace VIDEO_ID with the unique ID of the video from the platform (e.g., dQw4w9WgXcQ for YouTube).
  • Adjust width and height for desired sizing.

Allowed Domains:​

To maintain security and compatibility, only embed videos from the following domains are allowed:

Note:

Iframe-based videos cannot be rendered locally when using tools like techdocs-cli to preview documentation. They will render correctly only when the TechDocs site is hosted and accessed through the Internal Developer Portal (IDP).

Embedding Self-Hosted Videos​

For videos hosted in your repository or accessible via a direct URL, use the Markdown <video> tag:

<video controls>
  <source src="https://www.example.com/path-to-video.mp4" type="video/mp4">
</video>
  • Use this method for .mp4 or other self-hosted video formats stored in the repository.

You may want to make files available for download by your users such as PDF documents, images, or code templates. Download links for files included in your docs directory can be made by adding {: download } after a Markdown link.

[Link text](https://example.com/foo.jpg){: download }

The user's browser will download the file as download.jpg when the link is clicked.

Specify a file name to control the name the file will be given when it is downloaded:

[Link text](https://example.com/foo.jpg){: download="foo.jpg" }