Engineering Standards Documentation with MkDocs

This guide explains how to work with our MkDocs-based documentation system.

Local Development

Using Python

1. Install Python 3.11 or higher

2. Install dependencies:

   pip install -r requirements.txt
   

3. Run the development server:

   mkdocs serve
   

4. Open http://localhost:8000 in your browser

Using Docker

1. Install Docker and Docker Compose

2. Run the development server:

   docker compose up
   

3. Open http://localhost:8000 in your browser

Building for Production

Local Build

mkdocs build

The static site will be generated in the site directory.

Docker Build

docker build -t engineering-standards .
docker run -p 8000:8000 engineering-standards

Integration Options

Backstage Integration

The documentation is structured to be compatible with Backstage's TechDocs:

1. Add the following to your catalog-info.yaml:

   apiVersion: backstage.io/v1alpha1
   kind: Component
   metadata:
     name: engineering-standards
     annotations:
       backstage.io/techdocs-ref: dir:.
   

2. Update your Backstage configuration to include this repository

Confluence Integration

The documentation can be synced to Confluence using markdown support:

1. Set up Confluence space
2. Configure markdown rendering
3. Set up automated sync (optional)

File Structure

.
├── docs/                  # Documentation root
├── mkdocs.yml            # MkDocs configuration
├── requirements.txt      # Python dependencies
├── Dockerfile           # Container configuration
└── docker-compose.yml   # Docker Compose configuration

Customization

Theme Customization

The documentation uses Material for MkDocs theme. You can customize: - Colors and fonts in mkdocs.yml - Navigation structure - Search functionality - Additional features through plugins

Adding New Content

1. Add markdown files to appropriate directories
2. Update mkdocs.yml navigation if needed
3. Use supported markdown extensions:
4. Code highlighting
5. Admonitions
6. Task lists
7. Diagrams (Mermaid)