# freebsd/freebsd-doc architecture

> Architecture diagram of the GitHub repository freebsd/freebsd-doc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/freebsd/freebsd-doc
- Repository: https://github.com/freebsd/freebsd-doc

## Overview

This repository is the FreeBSD Documentation Project: multilingual documentation and a public website, with shared AsciiDoc extensions that add cross-references and links. The user-facing flow is documentation content becoming published web pages; the README identifies the content formats and website capabilities, but the provided tree does not include the documentation directory or site-rendering entry point. Edges among shared extensions are limited to wrapper-to-implementation registrations visible in the excerpts.

Main entry points: [`documentation/content`](https://github.com/freebsd/freebsd-doc/tree/main/documentation/content) (Books and Articles), [`website/content/en`](https://github.com/freebsd/freebsd-doc/tree/main/website/content/en) (FreeBSD Website), [`shared/lib/cross-document-references-macro.rb`](https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/cross-document-references-macro.rb) (Cross-doc Registration), [`shared/lib/inter-document-references-macro.rb`](https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/inter-document-references-macro.rb) (Inter-doc Registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Published Content"]
  node_docs["Books and Articles"]
  node_translations["Translations"]
end

subgraph group_web["Website Sections"]
  node_site["FreeBSD Website"]
  node_news["News and Events"]
  node_releases["Release Information"]
  node_security["Security Advisories"]
  node_community["Community Resources"]
end

subgraph group_extensions["AsciiDoc Extensions"]
  node_crossreg["Cross-doc Registration"]
  node_crossimpl["Cross-doc Macro<br/>[extension.rb]"]
  node_interreg["Inter-doc Registration"]
  node_interimpl["Inter-doc Macro<br/>[extension.rb]"]
  node_gitreg["Git Reference Registration<br/>[git-macro.rb]"]
  node_gitimpl["Git Reference Macro<br/>[extension.rb]"]
  node_manreg["Man Page Registration<br/>[man-macro.rb]"]
  node_manimpl["Man Page Macro<br/>[extension.rb]"]
  node_packreg["Package Registration<br/>[packages-macro.rb]"]
  node_packimpl["Package Macro<br/>[extension.rb]"]
  node_sections["Section Numbering"]
end

node_authors(("Contributors"))
node_reader(("Readers"))

node_authors -->|"author content"| node_docs
node_authors -->|"author content"| node_site
node_docs -.->|"published for"| node_reader
node_site -.->|"published for"| node_reader
node_crossreg -->|"loads and registers"| node_crossimpl
node_interreg -->|"loads and registers"| node_interimpl
node_gitreg -->|"loads and registers"| node_gitimpl
node_manreg -->|"loads and registers"| node_manimpl
node_packreg -->|"loads and registers"| node_packimpl

click node_docs "https://github.com/freebsd/freebsd-doc/tree/main/documentation/content"
click node_translations "https://github.com/freebsd/freebsd-doc/tree/main/shared"
click node_site "https://github.com/freebsd/freebsd-doc/tree/main/website/content/en"
click node_news "https://github.com/freebsd/freebsd-doc/tree/main/website/content/en/news"
click node_releases "https://github.com/freebsd/freebsd-doc/tree/main/website/content/en/releases"
click node_security "https://github.com/freebsd/freebsd-doc/tree/main/website/content/en/security"
click node_community "https://github.com/freebsd/freebsd-doc/tree/main/website/content/en/community"
click node_crossreg "https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/cross-document-references-macro.rb"
click node_crossimpl "https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/CrossDocumentReferencesMacro/extension.rb"
click node_interreg "https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/inter-document-references-macro.rb"
click node_interimpl "https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/InterDocumentReferencesMacro/extension.rb"
click node_gitreg "https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/git-macro.rb"
click node_gitimpl "https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/GitReferencesMacro/extension.rb"
click node_manreg "https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/man-macro.rb"
click node_manimpl "https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/ManPageMacro/extension.rb"
click node_packreg "https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/packages-macro.rb"
click node_packimpl "https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/PackagesMacro/extension.rb"
click node_sections "https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/sectnumoffset-treeprocessor.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_docs,node_translations toneBlue
class node_site,node_news,node_releases,node_security,node_community toneAmber
class node_crossreg,node_crossimpl,node_interreg,node_interimpl,node_gitreg,node_gitimpl,node_manreg,node_manimpl,node_packreg,node_packimpl,node_sections toneMint
class node_authors,node_reader toneIndigo
```

## Components

### Published Content

- [Books and Articles](https://github.com/freebsd/freebsd-doc/tree/main/documentation/content): `documentation/content`
- [Translations](https://github.com/freebsd/freebsd-doc/tree/main/shared): `shared`

### Website Sections

- [FreeBSD Website](https://github.com/freebsd/freebsd-doc/tree/main/website/content/en): `website/content/en`
- [News and Events](https://github.com/freebsd/freebsd-doc/tree/main/website/content/en/news): `website/content/en/news`
- [Release Information](https://github.com/freebsd/freebsd-doc/tree/main/website/content/en/releases): `website/content/en/releases`
- [Security Advisories](https://github.com/freebsd/freebsd-doc/tree/main/website/content/en/security): `website/content/en/security`
- [Community Resources](https://github.com/freebsd/freebsd-doc/tree/main/website/content/en/community): `website/content/en/community`

### AsciiDoc Extensions

- [Cross-doc Registration](https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/cross-document-references-macro.rb): `shared/lib/cross-document-references-macro.rb`
- [Cross-doc Macro](https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/CrossDocumentReferencesMacro/extension.rb): `shared/lib/CrossDocumentReferencesMacro/extension.rb`
- [Inter-doc Registration](https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/inter-document-references-macro.rb): `shared/lib/inter-document-references-macro.rb`
- [Inter-doc Macro](https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/InterDocumentReferencesMacro/extension.rb): `shared/lib/InterDocumentReferencesMacro/extension.rb`
- [Git Reference Registration](https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/git-macro.rb): `shared/lib/git-macro.rb`
- [Git Reference Macro](https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/GitReferencesMacro/extension.rb): `shared/lib/GitReferencesMacro/extension.rb`
- [Man Page Registration](https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/man-macro.rb): `shared/lib/man-macro.rb`
- [Man Page Macro](https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/ManPageMacro/extension.rb): `shared/lib/ManPageMacro/extension.rb`
- [Package Registration](https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/packages-macro.rb): `shared/lib/packages-macro.rb`
- [Package Macro](https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/PackagesMacro/extension.rb): `shared/lib/PackagesMacro/extension.rb`
- [Section Numbering](https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/sectnumoffset-treeprocessor.rb): `shared/lib/sectnumoffset-treeprocessor.rb`

### Other components

- **Contributors**
- **Readers**

## Connections

- Contributors → Books and Articles: author content
- Contributors → FreeBSD Website: author content
- Books and Articles → Readers: published for
- FreeBSD Website → Readers: published for
- Cross-doc Registration → Cross-doc Macro: loads and registers (evidence: `shared/lib/cross-document-references-macro.rb`)
- Inter-doc Registration → Inter-doc Macro: loads and registers (evidence: `shared/lib/inter-document-references-macro.rb`)
- Git Reference Registration → Git Reference Macro: loads and registers (evidence: `shared/lib/git-macro.rb`)
- Man Page Registration → Man Page Macro: loads and registers (evidence: `shared/lib/man-macro.rb`)
- Package Registration → Package Macro: loads and registers (evidence: `shared/lib/packages-macro.rb`)
