Documentation Template Guide

How to write and organize documentation for Abrino Docs

---

Quick Start

1. Copy _docs/_template.md to create a new documentation page
2. Update the front matter (the section between --- at the top)
3. Write your content using Markdown
4. Set the appropriate tags for publishing
5. Commit and push to publish

Tag-Based Publishing System

Available Tags

Publishing Control Tags

Tag	Purpose	Visibility
publish	Show on main website	Public
internal	Internal documentation only	Restricted
archive	Archived content	Archive section

Category Tags

Use descriptive category tags to organize content:

• devops - DevOps practices and tools
• kubernetes - Kubernetes documentation
• docker - Docker and containerization
• ci-cd - CI/CD pipelines
• security - Security practices
• monitoring - Monitoring and observability
• getting-started - Beginner guides
• advanced - Advanced topics
• troubleshooting - Troubleshooting guides
• api - API documentation
• tutorial - Step-by-step tutorials
• reference - Reference documentation

Example Front Matter

---
layout: default
title: "Deploying to Kubernetes"
nav_order: 5
parent: DevOps Guides
has_children: false
tags:
  - publish
  - devops
  - kubernetes
  - deployment
date: 2025-10-28
author: DevOps Team
description: "Complete guide to deploying applications to Kubernetes"
---

File Organization

_docs/
├── _template.md          # Template file (don't edit directly)
├── devops/               # DevOps documentation
│   ├── kubernetes/
│   ├── docker/
│   └── ci-cd/
├── development/          # Development guides
│   ├── apis/
│   ├── best-practices/
│   └── tutorials/
├── security/             # Security documentation
├── troubleshooting/      # Troubleshooting guides
└── archived/             # Archived content (tag: archive)

Writing Guidelines

1. Page Structure

Every page should have:

• Clear title and description
• Table of contents (for longer pages)
• Overview section
• Well-organized sections with headers
• Code examples with syntax highlighting
• Related documentation links

2. Code Examples

Use fenced code blocks with language specification:

```bash kubectl apply -f deployment.yaml ```

```yaml apiVersion: v1 kind: Pod ```

```python def hello_world(): print(“Hello, World!”) ```

3. Callouts and Alerts

Use Just the Docs callouts for important information:

{: .note }
> This is a note callout.

{: .important }
> This is important information.

{: .warning }
> This is a warning.

{: .highlight }
> This is highlighted content.

4. Navigation

Set nav_order to control page ordering in the sidebar:

• Lower numbers appear first
• Use increments of 5 or 10 to allow inserting pages later

For nested pages, use parent:

parent: DevOps Guides

For pages with child pages:

has_children: true

5. Search Optimization

• Use descriptive titles
• Include relevant keywords in the description
• Use proper heading hierarchy (H2, H3, H4)
• Add alternative terms in the content

Markdown Features

Headers

# H1 - Page Title (use once)
## H2 - Main Sections
### H3 - Subsections
#### H4 - Details

Lists

- Unordered list
- Another item
  - Nested item

1. Ordered list
2. Second item
   1. Nested ordered

Links

[External link](https://example.com)
[Internal link](../other-page)
[Link with title](https://example.com "Link title")

Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Images

![Alt text](/assets/images/screenshot.png)

Task Lists

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Obsidian Integration

This documentation is written in Obsidian and automatically published via Git.

Obsidian Features

• Wikilinks: Use [[Page Name]] for internal links (will be converted)
• Tags: Use both YAML front matter and #tags in content
• Daily notes: Keep work notes separate from published docs
• Templates: Use Obsidian templates based on _template.md

Git Workflow

1. Write/edit documentation in Obsidian
2. Use Obsidian Git plugin to commit changes
3. Push to the repository
4. GitHub Actions automatically builds and deploys
5. Changes appear on https://docs.abrino.cloud within minutes

Best Practices

✅ Do

• Use clear, descriptive titles
• Include code examples
• Add troubleshooting sections
• Link to related documentation
• Keep pages focused on one topic
• Update the date when editing
• Use proper tags for visibility control
• Test commands before documenting

❌ Don’t

• Use vague titles like “Configuration” or “Setup”
• Assume prior knowledge without linking prerequisites
• Leave outdated information (archive it instead)
• Forget to set publish tags
• Mix multiple unrelated topics on one page
• Hardcode sensitive information (use placeholders)

Publishing Workflow

Public Documentation (publish tag)

1. Write content following this guide
2. Add publish tag in front matter
3. Commit and push
4. Verify on main site after deployment

Internal Documentation (internal tag)

1. Write content as normal
2. Add internal tag instead of publish
3. Content will be filtered from main site
4. Accessible only to team members with repo access

Archiving Old Content (archive tag)

1. Find outdated documentation
2. Change tag from publish to archive
3. Move file to _docs/archived/ directory
4. Update any links pointing to it
5. Content moves to archive section

Maintenance Tasks

• Review and update content quarterly
• Archive outdated documentation
• Fix broken links
• Update screenshots and examples
• Improve search keywords
• Reorganize navigation as needed

---

Need Help?

• Check existing documentation for examples
• Review _docs/_template.md for structure
• Ask the team for review before publishing

Last Updated: 2025-10-28