Quick Start for Content Authors

Overview

This documentation site automatically aggregates content from all repositories with a /docs folder in our GitHub organizations. When you commit markdown files to your repository's /docs folder, they're automatically pulled into this unified site. We use Markdown for all documentation—a simple text format that's easy to write and read.

Working with Assets

You can include images, custom JavaScript, CSS, or any other assets directly in your repository. Place them alongside your markdown files and reference them with relative paths:

![Architecture diagram](./architecture.png)

If you organize assets in a subfolder:

![Logo](./images/logo.svg)
<script src="./scripts/custom.js"></script>

Important: Keep asset sizes reasonable! Avoid checking in large images (like 4K screenshots) as they unnecessarily bloat the repository. Optimize images before committing—for example, use ImageOptim which can be installed via Homebrew:

brew install imageoptim
imageoptim your-screenshot.png

Code Listings and Diagrams

Just like on GitHub, you can include syntax-highlighted code blocks and Mermaid diagrams:

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

```mermaid
graph LR
    A[User] --> B[API]
    B --> C[Database]
```

Previewing Changes

We don't have a "draft" mode—when you commit to main, your changes go live after the next build. To preview changes before merging, use GitHub's markdown preview in pull requests:

1. Create a PR with your documentation changes
2. Navigate to the changed .md file in the PR's "Files changed" tab
3. Click the "Preview" button (or the eye icon) to see how GitHub renders your markdown
4. This gives you a good approximation of how it will look on the docs site

Customizing Your Repo on the Index Page

The site's homepage displays all repositories in a card grid. You can control how your repository appears by adding frontmatter to your documentation's entry file (index.md, README.md, or readme.md).

ℹ️ Missing Entry File?
If your repository's /docs folder doesn't contain any of these entry files, a placeholder page will be automatically generated with instructions on how to add documentation. Users who click on your repository will see a helpful message with a link to add a README.md file.

---
teaser:
  roof-title: "My Service"
  title: "A comprehensive guide to using My Service for X, Y, and Z"
---

# My Service Documentation

Your content starts here...

What gets extracted:

• roof-title: The bold heading shown on the card (defaults to repository name if not set)
• title: The description text below the heading (defaults to "No description available" if not set)

Example card appearance:

Tips:

• Keep the roof-title short (2-4 words)
• Make the description informative but concise (under 100 characters works best)
• Use the repository name if no better title exists