How ozmanovic/static-site-generator works
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: main.py Build app · docs Published site · main.sh Preview script · test.sh Test script
Components 19
Source code
Python modules that parse, render, and orchestrate the site build.
- Build app · Coordinates discovery, conversion, templating, output creation, and asset copying; handles base-path deployment output.
src/main.py - Markdown nodes · Converts raw Markdown into structured text nodes for inline formatting and later HTML generation.
src/textnode.py - HTML nodes · Represents HTML as nodes and renders them into final HTML strings.
src/htmlnode.py - Page shell · Shared HTML wrapper that receives page title and generated content.
template.html - Static assets · CSS and images copied through without transformation.
static
Content
Markdown pages that become the generated site.
- Home page · Top-level site page in the content tree.
content/index.md - Contact · Standalone contact page.
content/contact/index.md - Glorfindel · Nested blog entry under the content hierarchy.
content/blog/glorfindel/index.md - Majesty · Nested blog entry under the content hierarchy.
content/blog/majesty/index.md - Tom · Nested blog entry under the content hierarchy.
content/blog/tom/index.md
Generated site
Deployable HTML and copied assets under docs/.
- Published site · Mirrored deployable website tree served directly from docs/.
docs - Home output · Generated HTML for the homepage.
docs/index.html - Contact output · Generated HTML for the contact page.
docs/contact/index.html - Glorfindel output · Generated HTML for the Glorfindel blog page.
docs/blog/glorfindel/index.html - Majesty output · Generated HTML for the Majesty blog page.
docs/blog/majesty/index.html - Tom output · Generated HTML for the Tom blog page.
docs/blog/tom/index.html
Scripts
Shell entry points for building, previewing, and testing.
- Build script · Runs the generator with a deployment base path.
build.sh - Preview script · Builds the site and starts a local server for preview.
main.sh - Test script · Runs the repository test suite.
test.sh
Connections 25
- 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.