docs: add README.md and license

2026-07-08 08:35:52 -05:00
parent c14c519293
commit 397bb8b3af
2 changed files with 89 additions and 0 deletions
@@ -0,0 +1,19 @@
+# Copyright (c) 2026 Stevan Freeborn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -1,2 +1,72 @@
 # Tolkien Fan Club

+A static site generator that converts Markdown content into HTML pages. Built from scratch as a learning exercise for [boot.dev](https://boot.dev).
+
+## Usage
+
+```bash
+# Build and serve locally
+./main.sh
+
+# Build with GitHub Pages basepath
+./build.sh
+
+# Run tests
+./test.sh
+```
+
+Or directly:
+
+```bash
+python3 -m src <destination> <basepath>
+python3 -m src "public" "/"
+python3 -m src "docs" "/tolkien-fan-club/"
+```
+
+## Project Structure
+
+```
+├── content/              # Markdown source files
+├── static/               # Static assets (CSS, images)
+├── template.html         # HTML template with {{ Title }} and {{ Content }}
+├── src/
+│   ├── cli.py            # Entry point
+│   ├── copier.py         # Static file copying
+│   ├── generator.py      # Page generation orchestration
+│   ├── template.py       # Template rendering + title extraction
+│   ├── nodes/
+│   │   ├── html.py       # HtmlNode base class
+│   │   ├── leaf.py       # LeafNode (void/self-closing elements)
+│   │   ├── parent.py     # ParentNode (nested elements)
+│   │   └── text.py       # TextNode / TextType + conversion to HTML
+│   ├── markdown/
+│   │   ├── blocks.py     # Block-level parsing (headings, code, lists, etc.)
+│   │   ├── extract.py    # Regex extraction for images and links
+│   │   ├── inlines.py    # Inline parsing (bold, italic, code, images, links)
+│   │   └── to_html.py    # Markdown → HTML conversion + block handlers
+│   └── tests/            # Test suite (48 tests)
+├── main.sh               # Build + serve locally
+├── build.sh              # Build for GitHub Pages
+└── test.sh               # Run test suite
+```
+
+## Pipeline
+
+```
+Markdown → blocks → block-type detection → inline parsing → TextNodes → HTML nodes → template injection
+```
+
+## Requirements
+
+- Python 3.13+
+- No external dependencies
+
+## Tests
+
+```bash
+python3 -m unittest discover -s src/tests -v
+```
+
+## License
+
+MIT