[WIP] Documentation Standards

Markdown Format Guidelines

All documentation and notes should be written in Markdown format, optimized for Obsidian compatibility.

Obsidian Compatibility

Internal Links (Graph View)

• Use [[Page Name]] syntax for internal links to other notes

• Links will automatically appear in Obsidian's graph view

• Example: [[Project Architecture]] or [[API Documentation]]

• Use [[Page Name|Display Text]] for custom link text

• Use [[Page Name#Heading]] to link to specific sections

Tags

• Use hashtags for categorization: #feature, #bug, #documentation

• Tags can be inline or in frontmatter

• Support nested tags: #project/backend, #project/frontend

Frontmatter (YAML)

---
title: Document Title
tags:
  - tag1
  - tag2
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

Block References

• Use ^block-id at the end of a paragraph to create block references

• Reference with [[Note Name#^block-id]]

Callouts

> [!note]
> This is a note callout

> [!warning]
> This is a warning callout

> [!tip]
> This is a tip callout

Code Blocks

• Use fenced code blocks with language identifiers

• Example:

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

Task Lists

• Use - [ ] for unchecked tasks

• Use - [x] for checked tasks

Tables

| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

Best Practices

1. Create Connections: Liberally use [[internal links]] to connect related concepts

2. Use Descriptive Names: Make file names clear and searchable

3. Add Context: Include frontmatter with metadata

4. Structure Content: Use headings (#, ##, ###) for hierarchy

5. Tag Consistently: Develop a consistent tagging system

6. Cross-Reference: Link related notes to build knowledge graphs

Example Document Structure

---
title: Feature Name
tags:
  - feature
  - backend
  - api
created: 2025-11-11
---

# Feature Name

## Overview
Brief description linking to [[Related Feature]] and [[Architecture]].

## Implementation
Details about implementation...

## References
- [[API Documentation]]
- [[Database Schema]]
- Related: #backend #api

This structure ensures maximum compatibility with Obsidian's graph view and knowledge management features.