This readme documents how to develop and deploy viaduct.airbnb.tech.

This site is built with MkDocs using the Material for MkDocs theme, which matches Airbnb's internal techdocs platform.

Install MkDocs and required dependencies:

pip install -r requirements.txt

Or manually:

pip install mkdocs mkdocs-material mkdocs-macros-plugin

Note: do not install mkdocs via Homebrew. Install it using pip as shown above.

To run the site locally:

mkdocs serve

Then open http://localhost:8000 in your browser. MkDocs will automatically reload when you make changes.

This site is deployed via AWS S3 and Cloudfront from a CI job internal to Airbnb. Manual deploy steps:

cd $VIADUCT_REPO
cd docs

# Build the MkDocs site
mkdocs build

# Generate Dokka API documentation
cd ../
./gradlew :core:tenant:api:dokkaGenerate
./gradlew :core:service:dokkaGenerate

# Deploy to S3
cd docs
aws s3 sync site/ s3://viaduct-airbnb-tech

The docs site includes API documentation generated by Dokka for the Viaduct codebase.

KDocs are split into two: one for tenant developers and one for service/platform developers.

These are generated via Gradle:

./gradlew :core:tenant:api:dokkaGenerate
./gradlew :core:service:dokkaGenerate

That task outputs HTML files to docs/site/apis/ and from there they are automatically included in the MkDocs build.

https://kotlinlang.org/docs/dokka-module-and-package-docs.html

Create a module.md file in the top-level of a module that is opted-in to Dokka. For example, engine/api/module.md. See link above for specific Markdown syntax.

This project uses djlint to validate that links from documentation pages to the API documentation (/apis/) point to pages that actually exist.

After building the site, run the linter from the docs/ directory:

cd docs

# Build the MkDocs site first
mkdocs build

# Run the link checker
PYTHONPATH=.:$PYTHONPATH djlint site/ --lint \
  --ignore "H005,H006,H013,H014,H021,H023,H025,H030,H031" \
  --include "LINK001"

The custom rule LINK001 checks that:

• Links from non-API pages to /apis/ paths point to existing files
• Pages inside /apis/ are skipped (those are auto-generated by Dokka)

If any broken links are found, the linter will report them with the file, line number, and the broken href.

The linter runs automatically in two places:

• The dokka job in the GitHub Actions build-and-test workflow.
• The internal Validate MkDocs Build JORB job (_infra/ci/jobs/validate_mkdocs_build.yml).

Both jobs build the MkDocs site and generate Dokka output before running djlint with the LINK001 rule.

docs/
├── mkdocs.yml          # MkDocs configuration
├── requirements.txt    # Python dependencies
├── plugins/            # Custom MkDocs macros
│   └── code_snippets.py
└── docs/               # Documentation content
    ├── index.md        # Homepage
    ├── about/          # About section
    ├── getting_started/# Getting started guides
    ├── developers/     # Developer documentation
    ├── service_engineers/
    ├── contributors/
    ├── tutorials/
    ├── blog/
    └── roadmap/

Use MkDocs admonition syntax for callouts:

!!! info
    This is an informational note.

!!! warning
    This is a warning.

!!! note "Custom Title"
    This is a note with a custom title.

Use fenced code blocks with language specifiers:

```kotlin
fun main() {
    println("Hello, World!") }

type Query {
    greeting: String }

### Linking to Other Pages

Use relative paths for internal links:

```markdown
[Getting Started](getting_started/index.md)
[Resolvers](developers/resolvers/index.md)

The site includes custom macros for embedding code from the Viaduct repository:

Embeds code snippets marked with tags in source files:

{{ codetag("demoapps/starwars/config/ViaductConfig.kt", "VIADUCT_CONFIG_1", lang="kotlin") }}

In the source file, mark the code with a tag comment:

// tag::VIADUCT_CONFIG_1[5] This is shown in service documentation
val config = ViaductConfig(...)

Embeds entire files or specific line ranges:

{{ codefile("core/tenant/api/src/main/kotlin/MyClass.kt", start=10, end=20, lang="kotlin") }}

Embeds files from GitHub with links:

{{ github("core/tenant/api/TenantModule.kt#L10-L20") }}

This MkDocs setup allows publishing the same markdown content to both:

• viaduct.airbnb.tech (public website)
• Airbnb internal techdocs (internal documentation)

The markdown files are standard and compatible with both MkDocs (for the public site) and Airbnb's internal techdocs system.