# ozmanovic/static-site-generator architecture

> Architecture diagram of the GitHub repository ozmanovic/static-site-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ozmanovic/static-site-generator
- Repository: https://github.com/ozmanovic/static-site-generator

## Overview

1. **Repository purpose and shape**  
   This is a Python static site generator. Its runtime path is: Markdown content in `content/` plus a shared HTML template in `template.html` are transformed into a generated website in `docs/`. The `docs/` tree is the deployable artifact, while `static/` holds assets that are copied through unchanged.

2. **Main build pipeline**  
   The generator walks the `content/` directory recursively, converts each `index.md` page into HTML, injects that HTML into the template, and writes the final file to a mirrored path under `docs/`. For example, `content/blog/tom/index.md` becomes `docs/blog/tom/index.html`.

3. **Core application entry point**  
   `src/main.py` is the orchestration layer. It coordinates content discovery, Markdown conversion, template rendering, output directory creation, and static asset copying. It also accepts an optional base-path argument, which changes how links and asset URLs are emitted for subdirectory deployments.

4. **Markdown parsing subsystem**  
   `src/textnode.py` is the Markdown/tokenization layer. It handles the conversion from raw Markdown text into structured text nodes, which is where inline formatting such as links, images, emphasis, and code likely gets interpreted before HTML generation.

5. **HTML generation subsystem**  
   `src/htmlnode.py` is the HTML tree/rendering layer. It represents HTML as node objects and renders those nodes into final HTML strings. This separates document structure from raw string concatenation and keeps the conversion pipeline composable.

6. **Page templating boundary**  
   `template.html` is the shared page shell. The generator substitutes the page title and generated content into the template, so layout is centralized and content files only need to describe page-specific Markdown.

7. **Static assets and deployment boundary**  
   `static/` contains CSS and images, and the build copies this directory into `docs/` without transformation. That means styling and media are deployment artifacts alongside the generated HTML, not part of the Markdown conversion path.

8. **Generated output mirror**  
   `docs/` is the output tree and mirrors the structure of `content/` and `static/`. This is important architecturally because the site is designed to be served directly from that directory, such as on GitHub Pages or any static host.

9. **Scripts as operational wrappers**  
   `build.sh` runs the generator with a deployment base path, while `main.sh` builds and starts a local HTTP server on port 8888 for previewing the generated site. `test.sh` is the test wrapper. These scripts are orchestration conveniences; the actual build logic lives in Python.

10. **Tests and quality boundaries**  
   `src/test_htmlnode.py`, `src/test_text_to_node.py`, and `src/test_textnode.py` validate the lower-level parsing and rendering primitives rather than the whole site. That suggests the repo’s critical correctness boundary is the Markdown-to-node-to-HTML conversion, with the directory traversal and file-copying layer built on top.

11. **Content model**  
   The `content/` tree includes the homepage, a contact page, and blog posts. The presence of nested folders implies the generator is designed around hierarchical pages, not a flat document list.

12. **External dependencies and runtime**  
   The project uses only the Python standard library, so the architecture is self-contained: no database, no package-managed frontend toolchain, and no external rendering service. Its only runtime dependency outside Python is the filesystem, plus an optional local web server for previewing the generated site.

Main entry points: [`src/main.py`](https://github.com/ozmanovic/static-site-generator/blob/main/src/main.py) (Build app), [`docs`](https://github.com/ozmanovic/static-site-generator/tree/main/docs) (Published site), [`main.sh`](https://github.com/ozmanovic/static-site-generator/blob/main/main.sh) (Preview script), [`test.sh`](https://github.com/ozmanovic/static-site-generator/blob/main/test.sh) (Test script)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Source code"]
  node_main_py["Build app<br/>orchestrator<br/>[main.py]"]
  node_textnode_py["Markdown nodes<br/>markdown parser<br/>[textnode.py]"]
  node_htmlnode_py["HTML nodes<br/>html renderer<br/>[htmlnode.py]"]
  node_template_html["Page shell<br/>template<br/>[template.html]"]
  node_static_assets[("Static assets<br/>asset tree")]
end

subgraph group_content["Content"]
  node_content_index["Home page<br/>markdown page<br/>[index.md]"]
  node_content_contact["Contact<br/>markdown page<br/>[index.md]"]
  node_content_blog_glorfindel["Glorfindel<br/>blog page<br/>[index.md]"]
  node_content_blog_majesty["Majesty<br/>blog page<br/>[index.md]"]
  node_content_blog_tom["Tom<br/>blog page<br/>[index.md]"]
end

subgraph group_output["Generated site"]
  node_docs_site[("Published site<br/>generated output")]
  node_docs_index["Home output<br/>generated html<br/>[index.html]"]
  node_docs_contact["Contact output<br/>generated html<br/>[index.html]"]
  node_docs_blog_glorfindel["Glorfindel output<br/>generated html<br/>[index.html]"]
  node_docs_blog_majesty["Majesty output<br/>generated html<br/>[index.html]"]
  node_docs_blog_tom["Tom output<br/>generated html<br/>[index.html]"]
end

subgraph group_ops["Scripts"]
  node_build_sh["Build script<br/>shell wrapper<br/>[build.sh]"]
  node_main_sh["Preview script<br/>shell wrapper<br/>[main.sh]"]
  node_test_sh["Test script<br/>shell wrapper<br/>[test.sh]"]
end

node_build_sh -->|"runs"| node_main_py
node_main_sh -->|"builds"| node_main_py
node_main_sh -->|"serves"| node_docs_site
node_test_sh -->|"tests"| node_textnode_py
node_test_sh -->|"tests"| node_htmlnode_py
node_main_py -->|"reads"| node_content_index
node_main_py -->|"reads"| node_content_contact
node_main_py -->|"reads"| node_content_blog_glorfindel
node_main_py -->|"reads"| node_content_blog_majesty
node_main_py -->|"reads"| node_content_blog_tom
node_main_py -->|"parses"| node_textnode_py
node_main_py -->|"renders"| node_htmlnode_py
node_main_py -->|"wraps"| node_template_html
node_main_py -->|"copies"| node_static_assets
node_main_py -->|"writes"| node_docs_index
node_main_py -->|"writes"| node_docs_contact
node_main_py -->|"writes"| node_docs_blog_glorfindel
node_main_py -->|"writes"| node_docs_blog_majesty
node_main_py -->|"writes"| node_docs_blog_tom
node_static_assets -->|"mirrors"| node_docs_site
node_docs_index -->|"part of"| node_docs_site
node_docs_contact -->|"part of"| node_docs_site
node_docs_blog_glorfindel -->|"part of"| node_docs_site
node_docs_blog_majesty -->|"part of"| node_docs_site
node_docs_blog_tom -->|"part of"| node_docs_site

click node_main_py "https://github.com/ozmanovic/static-site-generator/blob/main/src/main.py"
click node_textnode_py "https://github.com/ozmanovic/static-site-generator/blob/main/src/textnode.py"
click node_htmlnode_py "https://github.com/ozmanovic/static-site-generator/blob/main/src/htmlnode.py"
click node_template_html "https://github.com/ozmanovic/static-site-generator/blob/main/template.html"
click node_content_index "https://github.com/ozmanovic/static-site-generator/blob/main/content/index.md"
click node_content_contact "https://github.com/ozmanovic/static-site-generator/blob/main/content/contact/index.md"
click node_content_blog_glorfindel "https://github.com/ozmanovic/static-site-generator/blob/main/content/blog/glorfindel/index.md"
click node_content_blog_majesty "https://github.com/ozmanovic/static-site-generator/blob/main/content/blog/majesty/index.md"
click node_content_blog_tom "https://github.com/ozmanovic/static-site-generator/blob/main/content/blog/tom/index.md"
click node_static_assets "https://github.com/ozmanovic/static-site-generator/tree/main/static"
click node_docs_site "https://github.com/ozmanovic/static-site-generator/tree/main/docs"
click node_docs_index "https://github.com/ozmanovic/static-site-generator/blob/main/docs/index.html"
click node_docs_contact "https://github.com/ozmanovic/static-site-generator/blob/main/docs/contact/index.html"
click node_docs_blog_glorfindel "https://github.com/ozmanovic/static-site-generator/blob/main/docs/blog/glorfindel/index.html"
click node_docs_blog_majesty "https://github.com/ozmanovic/static-site-generator/blob/main/docs/blog/majesty/index.html"
click node_docs_blog_tom "https://github.com/ozmanovic/static-site-generator/blob/main/docs/blog/tom/index.html"
click node_build_sh "https://github.com/ozmanovic/static-site-generator/blob/main/build.sh"
click node_main_sh "https://github.com/ozmanovic/static-site-generator/blob/main/main.sh"
click node_test_sh "https://github.com/ozmanovic/static-site-generator/blob/main/test.sh"

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_main_py,node_textnode_py,node_htmlnode_py,node_template_html,node_static_assets toneBlue
class node_content_index,node_content_contact,node_content_blog_glorfindel,node_content_blog_majesty,node_content_blog_tom toneAmber
class node_docs_site,node_docs_index,node_docs_contact,node_docs_blog_glorfindel,node_docs_blog_majesty,node_docs_blog_tom toneMint
class node_build_sh,node_main_sh,node_test_sh toneRose
```

## Components

### Source code

Python modules that parse, render, and orchestrate the site build.

- [Build app](https://github.com/ozmanovic/static-site-generator/blob/main/src/main.py): orchestrator · Coordinates discovery, conversion, templating, output creation, and asset copying; handles base-path deployment output. · `src/main.py`
- [Markdown nodes](https://github.com/ozmanovic/static-site-generator/blob/main/src/textnode.py): markdown parser · Converts raw Markdown into structured text nodes for inline formatting and later HTML generation. · `src/textnode.py`
- [HTML nodes](https://github.com/ozmanovic/static-site-generator/blob/main/src/htmlnode.py): html renderer · Represents HTML as nodes and renders them into final HTML strings. · `src/htmlnode.py`
- [Page shell](https://github.com/ozmanovic/static-site-generator/blob/main/template.html): template · Shared HTML wrapper that receives page title and generated content. · `template.html`
- [Static assets](https://github.com/ozmanovic/static-site-generator/tree/main/static): asset tree · CSS and images copied through without transformation. · `static`

### Content

Markdown pages that become the generated site.

- [Home page](https://github.com/ozmanovic/static-site-generator/blob/main/content/index.md): markdown page · Top-level site page in the content tree. · `content/index.md`
- [Contact](https://github.com/ozmanovic/static-site-generator/blob/main/content/contact/index.md): markdown page · Standalone contact page. · `content/contact/index.md`
- [Glorfindel](https://github.com/ozmanovic/static-site-generator/blob/main/content/blog/glorfindel/index.md): blog page · Nested blog entry under the content hierarchy. · `content/blog/glorfindel/index.md`
- [Majesty](https://github.com/ozmanovic/static-site-generator/blob/main/content/blog/majesty/index.md): blog page · Nested blog entry under the content hierarchy. · `content/blog/majesty/index.md`
- [Tom](https://github.com/ozmanovic/static-site-generator/blob/main/content/blog/tom/index.md): blog page · Nested blog entry under the content hierarchy. · `content/blog/tom/index.md`

### Generated site

Deployable HTML and copied assets under docs/.

- [Published site](https://github.com/ozmanovic/static-site-generator/tree/main/docs): generated output · Mirrored deployable website tree served directly from docs/. · `docs`
- [Home output](https://github.com/ozmanovic/static-site-generator/blob/main/docs/index.html): generated html · Generated HTML for the homepage. · `docs/index.html`
- [Contact output](https://github.com/ozmanovic/static-site-generator/blob/main/docs/contact/index.html): generated html · Generated HTML for the contact page. · `docs/contact/index.html`
- [Glorfindel output](https://github.com/ozmanovic/static-site-generator/blob/main/docs/blog/glorfindel/index.html): generated html · Generated HTML for the Glorfindel blog page. · `docs/blog/glorfindel/index.html`
- [Majesty output](https://github.com/ozmanovic/static-site-generator/blob/main/docs/blog/majesty/index.html): generated html · Generated HTML for the Majesty blog page. · `docs/blog/majesty/index.html`
- [Tom output](https://github.com/ozmanovic/static-site-generator/blob/main/docs/blog/tom/index.html): generated html · Generated HTML for the Tom blog page. · `docs/blog/tom/index.html`

### Scripts

Shell entry points for building, previewing, and testing.

- [Build script](https://github.com/ozmanovic/static-site-generator/blob/main/build.sh): shell wrapper · Runs the generator with a deployment base path. · `build.sh`
- [Preview script](https://github.com/ozmanovic/static-site-generator/blob/main/main.sh): shell wrapper · Builds the site and starts a local server for preview. · `main.sh`
- [Test script](https://github.com/ozmanovic/static-site-generator/blob/main/test.sh): shell wrapper · Runs the repository test suite. · `test.sh`

## Connections

- Build script → Build app: runs · Deployment build invokes the Python generator with a base path.
- Preview script → Build app: builds · Preview workflow first generates the site.
- Preview script → Published site: serves · Local server exposes the generated docs tree.
- Test script → Markdown nodes: tests · Quality checks cover Markdown parsing behavior.
- Test script → HTML nodes: tests · Quality checks cover HTML rendering behavior.
- Build app → Home page: reads · Build orchestration discovers markdown pages recursively.
- Build app → Contact: reads · Build orchestration discovers markdown pages recursively.
- Build app → Glorfindel: reads · Build orchestration discovers markdown pages recursively.
- Build app → Majesty: reads · Build orchestration discovers markdown pages recursively.
- Build app → Tom: reads · Build orchestration discovers markdown pages recursively.
- Build app → Markdown nodes: parses · Markdown is tokenized into structured text nodes.
- Build app → HTML nodes: renders · Structured nodes are turned into HTML strings.
- Build app → Page shell: wraps · Rendered page content is injected into the shared template.
- Build app → Static assets: copies · Static files are copied through unchanged into the output tree.
- Build app → Home output: writes · Home page markdown becomes generated HTML output.
- Build app → Contact output: writes · Contact markdown becomes generated HTML output.
- Build app → Glorfindel output: writes · Blog markdown becomes generated HTML output.
- Build app → Majesty output: writes · Blog markdown becomes generated HTML output.
- Build app → Tom output: writes · Blog markdown becomes generated HTML output.
- Static assets → Published site: mirrors · Assets are copied into the deployable docs tree.
- Home output → Published site: part of · Generated homepage lives under the published site tree.
- Contact output → Published site: part of · Generated contact page lives under the published site tree.
- Glorfindel output → Published site: part of · Generated blog page lives under the published site tree.
- Majesty output → Published site: part of · Generated blog page lives under the published site tree.
- Tom output → Published site: part of · Generated blog page lives under the published site tree.
