# swiftlang/swift-book architecture

> Architecture diagram of the GitHub repository swiftlang/swift-book, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swiftlang/swift-book
- Repository: https://github.com/swiftlang/swift-book

## Overview

##### Main Components Structure

a) Content Layer
- Content into three main categories matching the directory structure:
- Guided Tour
- Language Guide
- Reference Manual

b) Build/Processing Layer
- Swift-DocC compilation system
- Binary tools (located in /bin directory)
- Redirect handling system

c) Output/Distribution Layer
- docs.swift.org publishing system
- Preview system for local development

##### Component Relationships

**[Source Content] → [Swift-DocC Compiler] → [Generated Documentation]**
- ↓
- [Binary Tools] → [Redirect System]
- ↓
- [Preview System] ← → [Published Output]

##### Detailed Component Breakdown

- Documentation structure (.docc directory organization)
- Build tools (bin directory utilities)
- Configuration files
- Asset management

##### Workflow Indicators

- Content authoring flow
- Build process flow
- Preview/testing flow
- Publication flow

##### The relationship between source content and generated output

Key Technical Elements to Include:
- Swift-DocC integration
- Markdown processing
- Asset handling
- Redirect management
- Preview capabilities
- Publication pipeline

Level of Detail:
- Keep high-level architectural components visible
- Abstract implementation details into logical groupings
- Content organization and build pipeline
- Transformation from source to published documentation

- How content flows through the system
- Where to add new documentation
- How the build process works
- How to preview and test changes
- How content gets published

Remember to include a note about the integration with Github for contribution workflow and the relationship with the Swift forums for larger changes and discussions.

This system design should reflect both the technical architecture and the content management aspects of the documentation system, making it clear how all pieces work together to produce the final published documentation.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Content
        GT["Guided Tour"]
        LG["Language Guide"]
        RM["Reference Manual"]
        ME["Main Entry"]:::entry
        AH["Assets"]:::assets
        RH["Revision History"]:::history
        
        ME --> GT
        ME --> LG
        ME --> RM
    end

    subgraph Configuration
        CF["Configuration Files"]:::config
        PH["Publishing Header"]:::config
        SH["Staging Header"]:::config
        FT["Footer"]:::config
        
        CF --> PH
        CF --> SH
        CF --> FT
    end

    subgraph "Build & Processing"
        SDC["Swift-DocC Compiler"]:::tool
        BT["Binary Tools"]:::tool
        RS["Redirect System"]:::tool
        
        SDC --> BT
        BT --> RS
    end

    subgraph "Distribution"
        PS["Preview System"]:::dist
        PUB["Publishing System"]:::dist
        
        PS <--> PUB
    end

    subgraph "Guidelines"
        CG["Contribution Guidelines"]:::guide
        SG["Style Guidelines"]:::guide
    end

    Content --> SDC
    Configuration --> SDC
    SDC --> PS
    SDC --> PUB
    
    %% Styles
    classDef entry fill:#a8d5e5
    classDef assets fill:#d1e8d1
    classDef history fill:#ffe6cc
    classDef config fill:#e6e6fa
    classDef tool fill:#90EE90
    classDef dist fill:#ffd700
    classDef guide fill:#f0e68c

    %% Click Events
    click GT "https://github.com/swiftlang/swift-book/tree/main/TSPL.docc/GuidedTour/"
    click LG "https://github.com/swiftlang/swift-book/tree/main/TSPL.docc/LanguageGuide/"
    click RM "https://github.com/swiftlang/swift-book/tree/main/TSPL.docc/ReferenceManual/"
    click BT "https://github.com/swiftlang/swift-book/tree/main/bin/"
    click RS "https://github.com/swiftlang/swift-book/tree/main/bin/redirects/"
    click PS "https://github.com/swiftlang/swift-book/tree/main/bin/update-book-preview"
    click PUB "https://github.com/swiftlang/swift-book/tree/main/bin/publish-book"
    click CF "https://github.com/swiftlang/swift-book/blob/main/TSPL.docc/Info.plist"
    click PH "https://github.com/swiftlang/swift-book/blob/main/TSPL.docc/header-publish.html"
    click SH "https://github.com/swiftlang/swift-book/blob/main/TSPL.docc/header-staging.html"
    click FT "https://github.com/swiftlang/swift-book/blob/main/TSPL.docc/footer.html"
    click ME "https://github.com/swiftlang/swift-book/blob/main/TSPL.docc/The-Swift-Programming-Language.md"
    click AH "https://github.com/swiftlang/swift-book/tree/main/TSPL.docc/Assets/"
    click RH "https://github.com/swiftlang/swift-book/tree/main/TSPL.docc/RevisionHistory/"
    click CG "https://github.com/swiftlang/swift-book/blob/main/CONTRIBUTING.md"
    click SG "https://github.com/swiftlang/swift-book/blob/main/Style.md"
```
