oxie 0.3.1__py3-none-any.whl

oxie/__init__.py

@@ -0,0 +1,28 @@
+'''
+oxie — a small static site/blog generator.
+
+Converts Markdown content into a styled, SEO-friendly static website
+using Jinja2 templates. A site is described by a SiteConfig (paths and
+optional features) and built by a Site:
+
+    from oxie import Site, SiteConfig
+
+    Site(SiteConfig()).build()
+
+To start a new site from scratch, use the command line instead:
+
+    oxie init myblog --title "My Blog"
+'''
+from .config import SiteConfig
+from .content import Post, Category
+from .scaffold import init_site
+from .site import Site, BlogIndex, IndexPage, generate_posts_jsonld
+from .updates import Update, UpdateReader
+
+__version__ = "0.3.1"
+
+__all__ = [
+    "Site", "SiteConfig", "Post", "Category", "BlogIndex", "IndexPage",
+    "generate_posts_jsonld", "init_site", "Update", "UpdateReader",
+    "__version__",
+]

oxie/__main__.py

@@ -0,0 +1,7 @@
+'''Entry point for `python -m oxie`.'''
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

oxie/cli.py

@@ -0,0 +1,83 @@
+'''
+Command line interface for oxie.
+
+    oxie init myblog --title "My Blog" --author "Me"
+    python -m oxie init myblog
+
+`init` is the only command: a site's own build.py is its build entry point.
+'''
+import argparse
+import sys
+
+from . import __version__
+from .scaffold import init_site
+
+
+def _cmd_init(args) -> int:
+    result = init_site(
+        target=args.path,
+        title=args.title,
+        author=args.author,
+        link=args.link,
+        description=args.description,
+        force=args.force,
+    )
+
+    for path in result["created"]:
+        print(f"  created  {path}")
+    for path in result["skipped"]:
+        print(f"  skipped  {path} (exists — use --force to overwrite)")
+
+    if not result["created"]:
+        print("\nNothing to do: every file already exists.")
+        return 0
+
+    steps = []
+    if args.path not in (".", ""):
+        steps.append(f"cd {args.path}")
+    steps.append("npm install       # Tailwind CSS v4")
+    steps.append("python build.py   # writes docs/")
+
+    print(f"\nSite created in {result['root']}\n")
+    print("Next steps:")
+    for step in steps:
+        print(f"  {step}")
+    print("\nThen open docs/index.html, or serve docs/ with a static file server.")
+    return 0
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="oxie",
+        description="oxie — a small static site/blog generator.",
+    )
+    parser.add_argument("--version", action="version", version=f"oxie {__version__}")
+    subparsers = parser.add_subparsers(dest="command")
+
+    init_parser = subparsers.add_parser(
+        "init",
+        help="create a new site (templates, Tailwind setup, sample content)",
+    )
+    init_parser.add_argument(
+        "path", nargs="?", default=".",
+        help="directory to create the site in (default: current directory)")
+    init_parser.add_argument("--title", default="My Site", help="site title")
+    init_parser.add_argument("--author", default="", help="author name")
+    init_parser.add_argument(
+        "--link", default="https://example.com",
+        help="public base URL, used for absolute links in structured data")
+    init_parser.add_argument(
+        "--description", default="A site built with oxie.", help="site description")
+    init_parser.add_argument(
+        "--force", action="store_true", help="overwrite existing files")
+    init_parser.set_defaults(func=_cmd_init)
+
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return 1
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

oxie/config.py

@@ -0,0 +1,93 @@
+'''
+Site configuration for the oxie static site generator.
+
+A SiteConfig describes one site: where its content, templates and output
+live, and which optional features (photography page, thumbnails, extra
+template pages, CSS pipeline) are enabled. The defaults match the classic
+oxie layout:
+
+    source/          markdown content (index.md, post/, page/, image/, static/)
+    src/             Jinja2 templates + meta_data.json + styles.css
+    docs/            generated output
+
+All relative paths are resolved against the current working directory,
+so a build is normally run from the site's root folder.
+'''
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Sequence
+
+DEFAULT_MARKDOWN_EXTENSIONS = [
+    'pymdownx.tilde', 'pymdownx.emoji', 'tables', 'meta', 'footnotes',
+    'md_in_html', 'extra',
+    'pymdownx.arithmatex', 'pymdownx.highlight', 'pymdownx.superfences',
+]
+
+DEFAULT_MARKDOWN_EXTENSION_CONFIGS = {
+    'pymdownx.arithmatex': {
+        'generic': True
+    },
+    'pymdownx.highlight': {
+        'use_pygments': True,
+        'noclasses': False,
+    },
+}
+
+
+@dataclass
+class SiteConfig:
+    # Core layout
+    source_dir: Path = Path('source')
+    template_dir: Path = Path('src')
+    output_dir: Path = Path('docs')
+    # Site metadata JSON (title, link, phrases, default image, ...)
+    meta_data_file: Path = Path('src/meta_data.json')
+
+    # Fall back to the templates bundled with oxie for any template the site
+    # does not define itself. Set False to fail loudly on a missing template.
+    use_bundled_templates: bool = True
+
+    # Markdown pipeline
+    markdown_extensions: List[str] = field(
+        default_factory=lambda: list(DEFAULT_MARKDOWN_EXTENSIONS))
+    markdown_extension_configs: Dict[str, dict] = field(
+        default_factory=lambda: dict(DEFAULT_MARKDOWN_EXTENSION_CONFIGS))
+
+    # Static assets: source directory -> output directory. None means the
+    # classic default: source/image -> docs/image, source/static -> docs/page.
+    collect_dirs: Optional[Dict[str, str]] = None
+
+    # Page titles excluded from the index page listing
+    index_excluded_titles: Sequence[str] = ('Terms of Service', 'Privacy Policy')
+
+    # Extra standalone pages rendered once with the site context:
+    # template file name -> output file name (relative to output_dir)
+    simple_pages: Dict[str, str] = field(default_factory=dict)
+
+    # Photography page: parses photos_md into albums and renders
+    # photography_template.html to photography.html
+    photography: bool = False
+    photos_md: Optional[Path] = None      # default: source_dir/photo/photos.md
+    thumbnails: bool = False
+    thumbnail_dir: Optional[Path] = None  # default: output_dir/image/photo
+    thumbnail_width: int = 600
+
+    # CSS pipeline: command run from the site root, or None to skip
+    css_build_command: Optional[Sequence[str]] = ('npm', 'run', 'build:css')
+    # Pygments highlight style written to output_dir/pygments.css, None to skip
+    pygments_style: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        self.source_dir = Path(self.source_dir)
+        self.template_dir = Path(self.template_dir)
+        self.output_dir = Path(self.output_dir)
+        self.meta_data_file = Path(self.meta_data_file)
+        if self.collect_dirs is None:
+            self.collect_dirs = {
+                str(self.source_dir / 'image'): str(self.output_dir / 'image'),
+                str(self.source_dir / 'static'): str(self.output_dir / 'page'),
+            }
+        if self.photos_md is None:
+            self.photos_md = self.source_dir / 'photo' / 'photos.md'
+        if self.thumbnail_dir is None:
+            self.thumbnail_dir = self.output_dir / 'image' / 'photo'

oxie/content.py

@@ -0,0 +1,122 @@
+'''
+Content models for the oxie static site generator.
+
+Post represents a single markdown document (a blog post or a static page)
+and Category a per-category listing page. Both are created by a Site,
+which supplies configuration, site metadata and templates.
+'''
+from pathlib import Path
+
+import frontmatter
+
+
+class Post:
+    '''
+    A blog post or page.
+    Posts and pages are the same, but they live in different directories
+    and appear in different areas of index.html.
+    '''
+
+    def __init__(self, md_path, html_path, site):
+        self.site = site
+        self.md_path = str(md_path)
+        self.html_path = str(html_path)
+        self.title = None
+        self.content = None
+        self.date = None
+        self.author = None
+        self.category = None
+        self.tags = []
+        self.read_time = None
+        self.link = None
+        self.summary = None
+        self.full_link = None
+        # Image is the cover image for the post, a path relative to the web
+        # root. The default comes from the site's meta_data.json.
+        self.image = site.meta_data["image"]
+        self.post_meta_data = None
+
+    def parse(self) -> None:
+        '''
+        Parse the markdown file and extract metadata and content
+        '''
+        with open(self.md_path, 'r') as md_file:
+            md_content = md_file.read()
+            post = frontmatter.loads(md_content)
+            self.post_meta_data = post.metadata
+            self.content = self.site.markdown().convert(post.content)
+
+            # link relative to the web root, and the full link with domain
+            self.link = '/' + Path(self.html_path).relative_to(
+                self.site.config.output_dir).as_posix()
+            self.full_link = self.site.meta_data["link"] + self.link
+
+            try:
+                self.title = self.post_meta_data["Title"]
+                self.author = self.post_meta_data["Authors"]
+                self.summary = self.post_meta_data["Summary"]
+                self.category = self.post_meta_data["Category"]
+                self.date = self.post_meta_data['Date']
+                # Last_modified is optional and defaults to the post date
+                self.last_modified = self.post_meta_data.get('Last_modified', self.date)
+                print(f"Processing {self.md_path} with last modified date {self.last_modified}")
+                self.tags = self.post_meta_data.get('Tags', [])
+                # cover image from the metadata, falling back to the default
+                self.image = self.post_meta_data.get("Image", self.image)
+            except KeyError:
+                print(f"Metadata not found in {self.md_path}")
+                pass
+
+    def render(self) -> None:
+        '''
+        Render the post to HTML
+        '''
+        rendered_html = self.site.template("template.html").render(
+            meta_data=self.site.meta_data,
+            post_meta_data=self.post_meta_data,
+            title=self.title,
+            author=self.author,
+            summary=self.summary,
+            category=self.category,
+            date=self.date,
+            last_modified=self.last_modified,
+            content=self.content,
+            phrases=self.site.meta_data["phrases"],
+            image=self.image,
+            tags=self.tags,
+            link=self.link,
+        )
+        with open(self.html_path, "w") as html_file:
+            html_file.write(rendered_html)
+
+
+class Category:
+    '''
+    A category listing page, rendered once per category.
+    Also carries the list of all tags used within the category.
+    '''
+
+    def __init__(self, site, posts, category) -> None:
+        self.site = site
+        self.meta_data = site.meta_data
+        self.posts = posts
+        self.category = category
+        self.tags = [tag for post in self.posts for tag in post.tags]
+        self.link = f"blog_{category}.html"
+        self.count = len(self.posts)
+        self.last_post = self.posts[0]
+
+    def render(self) -> None:
+        '''
+        Render the category page
+        '''
+        rendered_html = self.site.template("category_template.html").render(
+            title=self.meta_data["title"],
+            phrases=self.meta_data["phrases"],
+            posts=self.posts,
+            category=self.category,
+            tags=self.tags
+        )
+        output_path = self.site.config.output_dir / f"blog_{self.category}.html"
+        with open(output_path, "w") as html_file:
+            html_file.write(rendered_html)

oxie/photos.py

@@ -0,0 +1,100 @@
+'''
+Photography support for the oxie static site generator: parsing a
+photos.md album file and generating thumbnails for the photo gallery.
+'''
+import re
+from pathlib import Path
+
+from PIL import Image
+
+
+def resolve_photo_src(src: str, md_filepath: str, source_root) -> str:
+    '''
+    Resolve an image path written relative to the .md file into a path
+    relative to the web root (the output directory).
+    e.g. ../image/photo/file.jpg (relative to source/photo/) → image/photo/file.jpg
+    '''
+    md_dir = Path(md_filepath).parent
+    resolved = (md_dir / src).resolve()
+    return str(resolved.relative_to(Path(source_root).resolve()))
+
+
+def parse_photos_md(filepath: str, source_root) -> list:
+    '''
+    Parse photos.md into a list of albums.
+    Each album has a name and a list of photos with src, alt, and description.
+
+    Supported format:
+        ## Album Name
+
+        ![alt text](image/path.jpg)
+        Optional description paragraph on the next line.
+    '''
+    albums = []
+    current_album = {'name': None, 'photos': []}
+    current_photo = None
+
+    with open(filepath, 'r') as f:
+        lines = f.readlines()
+
+    for line in lines:
+        line = line.rstrip('\n')
+
+        # Album heading
+        if line.startswith('## '):
+            if current_photo:
+                current_album['photos'].append(current_photo)
+                current_photo = None
+            if current_album['photos'] or current_album['name']:
+                albums.append(current_album)
+            current_album = {'name': line[3:].strip(), 'photos': []}
+
+        # Image line
+        elif line.startswith('!['):
+            if current_photo:
+                current_album['photos'].append(current_photo)
+            m = re.match(r'!\[([^\]]*)\]\(([^)]+)\)', line)
+            if m:
+                web_src = resolve_photo_src(m.group(2), filepath, source_root)
+                current_photo = {'alt': m.group(1), 'src': web_src, 'description': ''}
+
+        # Description: non-empty line after an image, not a heading or image itself
+        elif current_photo and line.strip() and not line.startswith('#') and not line.startswith('!['):
+            current_photo['description'] = line.strip()
+
+        # Blank line flushes the current photo
+        elif not line.strip() and current_photo:
+            current_album['photos'].append(current_photo)
+            current_photo = None
+
+    # Flush remaining
+    if current_photo:
+        current_album['photos'].append(current_photo)
+    if current_album['photos'] or current_album['name']:
+        albums.append(current_album)
+
+    return albums
+
+
+def generate_thumbnails(photo_dir, thumb_width: int = 600) -> None:
+    '''
+    Generate thumbnails for all images in photo_dir.
+    Thumbnails are written to photo_dir/thumb/ at thumb_width pixels wide,
+    preserving aspect ratio. Skips non-image files.
+    '''
+    photo_path = Path(photo_dir)
+    thumb_path = photo_path / 'thumb'
+    thumb_path.mkdir(parents=True, exist_ok=True)
+
+    image_exts = {'.jpg', '.jpeg', '.png', '.webp', '.gif'}
+    for img_file in photo_path.iterdir():
+        if img_file.suffix.lower() not in image_exts:
+            continue
+        dest = thumb_path / img_file.name
+        with Image.open(img_file) as img:
+            img = img.convert('RGB')
+            ratio = thumb_width / img.width
+            new_size = (thumb_width, int(img.height * ratio))
+            thumb = img.resize(new_size, Image.LANCZOS)
+            thumb.save(dest, quality=80, optimize=True)
+    print(f"Thumbnails written to {thumb_path}")

oxie/scaffold.py

@@ -0,0 +1,236 @@
+'''
+Site scaffolding for oxie: create a complete, buildable site in one command.
+
+`init_site()` writes the default templates, a Tailwind CSS v4 setup, sample
+content and a `build.py`, so a new site goes from empty directory to built
+HTML with `npm install && python build.py`.
+'''
+import json
+import shutil
+from datetime import date
+from pathlib import Path
+from typing import List
+
+TEMPLATE_PACKAGE_DIR = Path(__file__).parent / "templates" / "default"
+
+# Template files copied verbatim into the new site's template directory.
+TEMPLATE_FILES = [
+    "base.html",
+    "index.html",
+    "template.html",
+    "blog_template.html",
+    "category_template.html",
+]
+
+DEFAULT_PHRASES = [
+    "Well begun is half done.",
+    "Write drunk, edit sober.",
+    "A journey of a thousand miles begins with a single step.",
+]
+
+BUILD_PY = '''\
+"""Build script for {title}.
+
+Run with:  python build.py
+Requires:  pip install -r requirements.txt  &&  npm install
+"""
+from oxie import Site, SiteConfig
+
+config = SiteConfig(
+    # source/, src/ and docs/ are the defaults; override them if you move things.
+    collect_dirs={{
+        # Everything in source/image is copied to docs/image ...
+        "source/image": "docs/image",
+        # ... and source/static lands at the site root, next to index.html.
+        "source/static": "docs",
+    }},
+    # Syntax highlighting stylesheet written to docs/pygments.css.
+    pygments_style="github-dark",
+    # Compiles src/styles.css into docs/styles.css with Tailwind.
+    # Set to None if you want to manage CSS yourself.
+    css_build_command=("npm", "run", "build:css"),
+)
+
+if __name__ == "__main__":
+    Site(config).build()
+'''
+
+PACKAGE_JSON = {
+    "name": "site",
+    "private": True,
+    "scripts": {
+        "build:css": "tailwindcss -i src/styles.css -o docs/styles.css --minify",
+        "watch:css": "tailwindcss -i src/styles.css -o docs/styles.css --watch",
+    },
+    "devDependencies": {
+        "@tailwindcss/cli": "^4.3.3",
+        "@tailwindcss/typography": "^0.5.20",
+    },
+}
+
+REQUIREMENTS_TXT = "oxie==0.3.1\n"
+
+GITIGNORE = """\
+__pycache__/
+*.pyc
+.venv/
+node_modules/
+"""
+
+INDEX_MD = '''\
+Title:   {title}
+Summary: {description}
+Authors: {author}
+Date:    {today}
+
+## Hello
+
+This is your home page. It is written in `source/index.md`.
+
+Unlike posts, this file uses simple `Key: value` lines at the top instead of
+`---` fenced frontmatter — that is the one format asymmetry in oxie.
+
+Edit it, run `python build.py`, and open `docs/index.html`.
+'''
+
+POST_MD = '''\
+---
+Title: Hello World
+Summary: The first post on {title} — how posts work in oxie.
+Authors: {author}
+Date: {today}
+Category: Blog
+Tags: [oxie, writing]
+---
+
+# Hello World
+
+Every file in `source/post/` becomes a post. The frontmatter above uses
+**capitalised keys** (`Title`, `Authors`, `Date`, `Category`, `Tags`), which
+oxie reads to build the blog index and per-category pages.
+
+## Things that work out of the box
+
+- Tables, footnotes[^1] and `~~strikethrough~~`
+- Fenced code with syntax highlighting:
+
+```python
+from oxie import Site, SiteConfig
+
+Site(SiteConfig()).build()
+```
+
+- Maths, via `pymdownx.arithmatex`
+- Category pages: this post is in *Blog*, so it appears on `blog_Blog.html`
+
+[^1]: Footnotes look like this.
+
+## Next steps
+
+Delete this file, write your own, and rebuild.
+'''
+
+ABOUT_MD = '''\
+---
+Title: About
+Summary: About {title}.
+Authors: {author}
+Date: {today}
+Category: Page
+Tags: [about]
+---
+
+# About
+
+Files in `source/page/` are pages rather than posts: they are listed on the
+home page but stay out of the blog index.
+
+Tell your readers who you are here.
+'''
+
+
+def _write(path: Path, content: str, force: bool, created: List[str], skipped: List[str]) -> None:
+    '''Write content to path unless it exists and force is False.'''
+    if path.exists() and not force:
+        skipped.append(str(path))
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+    created.append(str(path))
+
+
+def init_site(
+    target: str = ".",
+    title: str = "My Site",
+    author: str = "",
+    link: str = "https://example.com",
+    description: str = "A site built with oxie.",
+    force: bool = False,
+) -> dict:
+    '''
+    Create a new oxie site in `target`.
+
+    Existing files are left alone unless `force` is True, so running this in
+    a directory that already has content is safe.
+
+    Returns a dict with 'created' and 'skipped' file lists.
+    '''
+    root = Path(target)
+    created: List[str] = []
+    skipped: List[str] = []
+    today = date.today().isoformat()
+    fields = {
+        "title": title,
+        "author": author or "Anonymous",
+        "today": today,
+        "description": description,
+    }
+
+    # Content directories, including the ones the build copies verbatim
+    for sub in ("source/post", "source/page", "source/image", "source/static", "docs"):
+        (root / sub).mkdir(parents=True, exist_ok=True)
+
+    # Jinja templates
+    for name in TEMPLATE_FILES:
+        destination = root / "src" / name
+        if destination.exists() and not force:
+            skipped.append(str(destination))
+            continue
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(TEMPLATE_PACKAGE_DIR / name, destination)
+        created.append(str(destination))
+
+    # Tailwind v4 entry point
+    _write(root / "src" / "styles.css",
+           (TEMPLATE_PACKAGE_DIR / "styles.css").read_text(), force, created, skipped)
+
+    # Site metadata
+    meta_data = {
+        "title": title,
+        "description": description,
+        "author": author or "Anonymous",
+        "date": today,
+        "link": link.rstrip("/"),
+        "image": "image/default.png",
+        "phrases": DEFAULT_PHRASES,
+    }
+    _write(root / "src" / "meta_data.json",
+           json.dumps(meta_data, indent=4, ensure_ascii=False) + "\n",
+           force, created, skipped)
+
+    # Content
+    _write(root / "source" / "index.md", INDEX_MD.format(**fields), force, created, skipped)
+    _write(root / "source" / "post" / "hello-world.md", POST_MD.format(**fields), force, created, skipped)
+    _write(root / "source" / "page" / "about.md", ABOUT_MD.format(**fields), force, created, skipped)
+
+    # Build script and project files
+    _write(root / "build.py", BUILD_PY.format(title=title), force, created, skipped)
+    package_json = dict(PACKAGE_JSON)
+    package_json["name"] = "".join(
+        c if c.isalnum() or c in "-_" else "-" for c in title.lower()
+    ).strip("-") or "site"
+    _write(root / "package.json", json.dumps(package_json, indent=2) + "\n", force, created, skipped)
+    _write(root / "requirements.txt", REQUIREMENTS_TXT, force, created, skipped)
+    _write(root / ".gitignore", GITIGNORE, force, created, skipped)
+
+    return {"created": created, "skipped": skipped, "root": str(root)}