# jgm/djot architecture

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

- Interactive diagram: https://gitdiagram.com/jgm/djot
- Repository: https://github.com/jgm/djot

## Overview

##### Project’s Nature and Purpose
- The project is an open-source tool that defines a markup language (Djot) derived from CommonMark. Its purpose is to offer a simpler, more predictable, and fully featured markup syntax.
- Its README explains the differences from CommonMark, design goals (e.g., linear-time parsing, local inline parsing, simplified emphasis rules), and examples of syntax. It serves as documentation and reference for the syntax.
- Additionally, the repository includes supporting documentation (in the doc folder), tooling for editors (in the editors folder for Vim and Emacs), build configurations (Makefiles), and even a basic web demo (in the web folder).

##### Analyzing the File Tree Structure
- Top-level directories and files:
- .github directory and files: Contains GitHub configuration (e.g., FUNDING info), which underlines community engagement.
- LICENSE, README.md, and root-level Makefile: Core project metadata and build scripts.
- Documentation (doc folder): Contains the syntax description, cheatsheet, code examples, quick start guide, and even styling files (syntax.css, syntax.html, syntax.md). This shows a self-contained documentation structure.
- Editors folder: Divided into subdirectories for Emacs and Vim, which provide language support (syntax highlighting, file detection). Emphasize that they define language-specific integration points.
- Web folder: Contains a Makefile, an index.html, and other media (djot.wav) indicating a simple web interface or demo.
- Thus, the repository is organized into clearly separated concerns: core documentation and language description, editor support, and demonstration tooling.

##### Illustrating Architectural Components
- Main Components:
- Documentation & Reference:
▸ README.md and doc folder: Represents the user manual, syntax description, cheatsheet, and quick start.
- Editor Tooling:
▸ The editors directory (with both Vim and Emacs subdirectories): Represents integration modules for code editors.
- Build and Configuration:
▸ Makefile(s) at the root and in the web subfolder, plus GitHub configuration files: Indicate build automation and repository management.
- Web Demo / Playground:
▸ The web folder: Represents a simple front-end that provides an interactive demo (as also mentioned in the README via the djot playground link).
- Optional conceptual components (from the README’s list of implementations):
- External Implementations:
▸ Although not part of the repository file tree, the README references multiple language implementations (djot.js, djot.lua, etc.). These should be shown as external integration components or “consumers” of the core djot syntax specification.
- Parsing Engine (Core Syntax Engine):

##### Defining Connections and Data Flow
- The “Documentation” component to “Editor Tooling” as the editors use the detailed syntax for enabling proper highlighting and file detection.
- The “Build and Configuration” component pointing to the “Web Demo,” showing that scripts and static files are used to render the demo.
- “Core Syntax / Parsing Engine” (conceptual) to both “External Implementations” and “Documentation” – conveying that the design principles and syntax rules are used across multiple outcomes.
- The README and doc files inform both the usage and integration in editors.
- The Makefile ensures proper builds for the web demo and any bundled tooling.

##### Architectural Patterns and Design Principles
- Layered Separation:
- Separation between the “Presentation” (web demo / editor tooling) and the “Specification” (documentation and syntax rules).
- Modularity and Extensibility:
- That the project is designed to be used in multiple contexts via different implementations. Indicate that each implementation (e.g., djot.js, djot.lua) is an independent module built around the same syntax foundation.
- Build Automation:
- That the integration of Makefiles and GitHub configuration indicates an automated and continuously integrated workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Specification Layer
    subgraph "Specification Layer"
        CP["Core Syntax Parsing Engine"]:::concept
        subgraph "Documentation & Reference"
            DR1["README.md"]:::resource
            DR2["doc folder"]:::resource
        end
    end

    %% Editor Tooling
    subgraph "Editor Tooling"
        ET1["Emacs Support"]:::resource
        ET2["Vim ftdetect"]:::resource
        ET3["Vim syntax"]:::resource
    end

    %% Build & Configuration
    subgraph "Build & Configuration"
        BC1["Root Makefile"]:::resource
        BC2[".github (FUNDING)"]:::resource
    end

    %% Web Demo
    subgraph "Web Demo"
        WD1["index.html"]:::resource
        WD2["Web Makefile"]:::resource
        WD3["djot.wav"]:::resource
    end

    %% External Implementations
    EI["External Implementations"]:::concept

    %% Connections
    CP -->|"defines"| DR1
    CP -->|"defines"| EI
    DR1 -->|"informs"| ET1
    DR1 -->|"specifies"| EI
    BC1 -->|"builds"| WD1
    BC2 -->|"builds"| WD1

    %% Click Events for Documentation & Reference
    click DR1 "https://github.com/jgm/djot/blob/main/README.md"
    click DR2 "https://github.com/jgm/djot/tree/main/doc/"

    %% Click Events for Editor Tooling
    click ET1 "https://github.com/jgm/djot/blob/main/editors/emacs/djot.el"
    click ET2 "https://github.com/jgm/djot/blob/main/editors/vim/ftdetect/djot.vim"
    click ET3 "https://github.com/jgm/djot/blob/main/editors/vim/syntax/djot.vim"

    %% Click Events for Build & Configuration
    click BC1 "https://github.com/jgm/djot/tree/main/Makefile"
    click BC2 "https://github.com/jgm/djot/blob/main/.github/FUNDING.yml"

    %% Click Events for Web Demo
    click WD1 "https://github.com/jgm/djot/blob/main/web/index.html"
    click WD2 "https://github.com/jgm/djot/tree/main/web/Makefile"
    click WD3 "https://github.com/jgm/djot/blob/main/web/djot.wav"

    %% Styles
    classDef concept fill:#f9e79f,stroke:#e67e22,stroke-width:2px;
    classDef resource fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
```
