essayist 0.1.0__tar.gz

essayist-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ayx-dg
+
+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.

essayist-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: essayist
+Version: 0.1.0
+Summary: A Pandoc + Jinja2 static site generator for Markdown blogs.
+Author: ayx-dg
+License: MIT
+Project-URL: Homepage, https://github.com/ayx-dg/essayist
+Project-URL: Repository, https://github.com/ayx-dg/essayist
+Keywords: static-site-generator,blog,markdown,pandoc,jinja2
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2
+Requires-Dist: pyyaml
+Requires-Dist: tomli; python_version < "3.11"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# essayist
+
+A lightweight static site generator for Markdown blogs, powered by
+[Pandoc](https://pandoc.org/) and [Jinja2](https://jinja.palletsprojects.com/).
+
+Convert a directory of Markdown posts (with YAML front matter) into a styled
+HTML blog with an index page and an RSS feed.
+
+## Requirements
+
+- Python ≥ 3.10
+- [Pandoc](https://pandoc.org/installing.html) available on `PATH`
+
+## Install
+
+```bash
+pip install essayist
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/ayx-dg/essayist
+cd essayist
+pip install -e .
+```
+
+## Quick start
+
+### 1. Set up your Markdown directory
+
+Create a `markdown/posts/` folder and add `.md` files with YAML front matter:
+
+```markdown
+---
+title: My First Post
+date: 2025-01-15
+tags: [intro, welcome]
+publish: public
+---
+
+# My First Post
+
+Here is the body of my post, written in Markdown.
+```
+
+### 2. Create a config file
+
+Save this as `essayist.toml` in your project root:
+
+```toml
+markdown_dir = "markdown/posts"
+post_dir     = "public/posts"
+blogname     = "My Blog"
+site_url     = "https://example.com"
+panargs      = ["--mathml", "--toc", "--shift-heading-level-by=1"]
+
+build_index = true
+index_title = "All Posts"
+build_rss   = true
+home_md      = "markdown/index.md"
+home_output  = "public/index.html"
+style_css    = "style-note.css"
+```
+
+### 3. Build
+
+```bash
+essayist build
+```
+
+Output will be written to `public/`. Open `public/index.html` in a browser.
+
+## CLI usage
+
+```
+essayist build [--config essayist.toml] [OPTIONS]
+essayist version
+```
+
+CLI flags override the corresponding config-file values:
+
+| Flag             | Description                        |
+|------------------|------------------------------------|
+| `-c, --config`   | Path to TOML config (default: `essayist.toml`) |
+| `--markdown-dir` | Directory with Markdown posts      |
+| `--post-dir`     | Output directory for rendered HTML |
+| `--template-dir` | Custom Jinja2 template directory   |
+| `--blogname`     | Blog name for page titles          |
+| `--site-url`     | Base URL for RSS feeds             |
+| `--gallery`      | Enable the gallery Lua filter      |
+
+## Python API
+
+```python
+from essayist import Blog, Config, build_site
+
+# High-level: load config and build everything
+cfg = Config(
+    markdown_dir="markdown/posts",
+    post_dir="public/posts",
+    blogname="My Blog",
+    site_url="https://example.com",
+    panargs=["--mathml", "--toc"],
+)
+build_site(cfg)
+
+# Or use the Blog class directly
+blog = Blog(
+    markdown_dir="markdown/posts",
+    post_dir="public/posts",
+    template_dir="path/to/custom/templates",  # None → use bundled defaults
+)
+blog.update_data()
+blog.build_posts()
+blog.build_index()
+blog.build_rss("public/posts/rss.xml")
+```
+
+## Config reference
+
+All keys in `essayist.toml`:
+
+| Key               | Type        | Default           | Description                                        |
+|-------------------|-------------|-------------------|----------------------------------------------------|
+| `markdown_dir`    | string      | `markdown/posts`  | Directory with `.md` post files                    |
+| `post_dir`        | string      | `public/posts`    | Output directory for rendered HTML                 |
+| `template_dir`    | string/null | `null` (bundled)  | Jinja2 template directory (`null` = use defaults)  |
+| `blogname`        | string      | `""`              | Blog name appended to page titles                  |
+| `google_group_id` | string      | `""`              | Enables the email-comment block in posts           |
+| `site_url`        | string      | `https://example.com` | Base URL used in RSS `<link>` tags            |
+| `panargs`         | array       | `[]`              | Extra flags passed to Pandoc                       |
+| `gallery`         | bool        | `false`           | Enable the bundled image-gallery Lua filter        |
+| `build_index`     | bool        | `true`            | Generate the post-list index page                  |
+| `index_title`     | string      | `Index`           | Title for the index page                           |
+| `build_rss`       | bool        | `true`            | Generate an RSS 2.0 feed                           |
+| `rss_path`        | string/null | `<post_dir>/rss.xml` | Where to write the RSS feed                   |
+| `home_md`         | string/null | `null`            | Markdown file for the home page (if any)           |
+| `home_template`   | string      | `home.html`       | Template used to render the home page              |
+| `home_output`     | string      | `public/index.html` | Output path for the home page                   |
+| `style_css`       | string/null | `null`            | CSS file copied next to rendered posts             |
+| `data_path`       | string      | `data.json`       | Path for the auto-generated post index             |
+
+## Post front matter
+
+Every Markdown post should start with a YAML front matter block:
+
+```yaml
+---
+title: Post Title          # required
+date: 2025-01-15           # used for ordering in index and RSS
+tags: [tag1, tag2]         # optional, passed to templates
+publish: public            # public | draft | unlisted
+maillist_title: ...        # optional, email comment link
+google_group_link: ...     # optional, link to mail thread
+---
+```
+
+**Visibility rules:**
+
+- `public` — appears in index and RSS
+- `draft` — skipped entirely (existing output is cleaned up)
+- `unlisted` — appears in RSS but not in the index
+
+## Templates
+
+The package ships with five default templates:
+
+| Template     | Purpose                         |
+|-------------|---------------------------------|
+| `header.html` | `<head>` block with CSS and RSS link |
+| `footer.html` | Footer with RSS link           |
+| `post.html`   | Single blog post page          |
+| `index.html`  | Post listing (all public posts)|
+| `home.html`   | Home / landing page             |
+
+Supply a `template_dir` in your config to override any of these. The templates
+use [Jinja2](https://jinja.palletsprojects.com/) syntax and receive variables
+like `heading`, `paragraphs`, `title`, `prev_post`, `next_post`, etc.
+
+## Bundled Lua filters
+
+| Filter       | Description                              |
+|-------------|------------------------------------------|
+| `gallery.lua` | Groups images in a paragraph into a responsive flex gallery |
+
+Enable with `gallery = true` in config, or pass `--gallery` on the CLI.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+## License
+
+MIT

essayist-0.1.0/README.md

@@ -0,0 +1,198 @@
+# essayist
+
+A lightweight static site generator for Markdown blogs, powered by
+[Pandoc](https://pandoc.org/) and [Jinja2](https://jinja.palletsprojects.com/).
+
+Convert a directory of Markdown posts (with YAML front matter) into a styled
+HTML blog with an index page and an RSS feed.
+
+## Requirements
+
+- Python ≥ 3.10
+- [Pandoc](https://pandoc.org/installing.html) available on `PATH`
+
+## Install
+
+```bash
+pip install essayist
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/ayx-dg/essayist
+cd essayist
+pip install -e .
+```
+
+## Quick start
+
+### 1. Set up your Markdown directory
+
+Create a `markdown/posts/` folder and add `.md` files with YAML front matter:
+
+```markdown
+---
+title: My First Post
+date: 2025-01-15
+tags: [intro, welcome]
+publish: public
+---
+
+# My First Post
+
+Here is the body of my post, written in Markdown.
+```
+
+### 2. Create a config file
+
+Save this as `essayist.toml` in your project root:
+
+```toml
+markdown_dir = "markdown/posts"
+post_dir     = "public/posts"
+blogname     = "My Blog"
+site_url     = "https://example.com"
+panargs      = ["--mathml", "--toc", "--shift-heading-level-by=1"]
+
+build_index = true
+index_title = "All Posts"
+build_rss   = true
+home_md      = "markdown/index.md"
+home_output  = "public/index.html"
+style_css    = "style-note.css"
+```
+
+### 3. Build
+
+```bash
+essayist build
+```
+
+Output will be written to `public/`. Open `public/index.html` in a browser.
+
+## CLI usage
+
+```
+essayist build [--config essayist.toml] [OPTIONS]
+essayist version
+```
+
+CLI flags override the corresponding config-file values:
+
+| Flag             | Description                        |
+|------------------|------------------------------------|
+| `-c, --config`   | Path to TOML config (default: `essayist.toml`) |
+| `--markdown-dir` | Directory with Markdown posts      |
+| `--post-dir`     | Output directory for rendered HTML |
+| `--template-dir` | Custom Jinja2 template directory   |
+| `--blogname`     | Blog name for page titles          |
+| `--site-url`     | Base URL for RSS feeds             |
+| `--gallery`      | Enable the gallery Lua filter      |
+
+## Python API
+
+```python
+from essayist import Blog, Config, build_site
+
+# High-level: load config and build everything
+cfg = Config(
+    markdown_dir="markdown/posts",
+    post_dir="public/posts",
+    blogname="My Blog",
+    site_url="https://example.com",
+    panargs=["--mathml", "--toc"],
+)
+build_site(cfg)
+
+# Or use the Blog class directly
+blog = Blog(
+    markdown_dir="markdown/posts",
+    post_dir="public/posts",
+    template_dir="path/to/custom/templates",  # None → use bundled defaults
+)
+blog.update_data()
+blog.build_posts()
+blog.build_index()
+blog.build_rss("public/posts/rss.xml")
+```
+
+## Config reference
+
+All keys in `essayist.toml`:
+
+| Key               | Type        | Default           | Description                                        |
+|-------------------|-------------|-------------------|----------------------------------------------------|
+| `markdown_dir`    | string      | `markdown/posts`  | Directory with `.md` post files                    |
+| `post_dir`        | string      | `public/posts`    | Output directory for rendered HTML                 |
+| `template_dir`    | string/null | `null` (bundled)  | Jinja2 template directory (`null` = use defaults)  |
+| `blogname`        | string      | `""`              | Blog name appended to page titles                  |
+| `google_group_id` | string      | `""`              | Enables the email-comment block in posts           |
+| `site_url`        | string      | `https://example.com` | Base URL used in RSS `<link>` tags            |
+| `panargs`         | array       | `[]`              | Extra flags passed to Pandoc                       |
+| `gallery`         | bool        | `false`           | Enable the bundled image-gallery Lua filter        |
+| `build_index`     | bool        | `true`            | Generate the post-list index page                  |
+| `index_title`     | string      | `Index`           | Title for the index page                           |
+| `build_rss`       | bool        | `true`            | Generate an RSS 2.0 feed                           |
+| `rss_path`        | string/null | `<post_dir>/rss.xml` | Where to write the RSS feed                   |
+| `home_md`         | string/null | `null`            | Markdown file for the home page (if any)           |
+| `home_template`   | string      | `home.html`       | Template used to render the home page              |
+| `home_output`     | string      | `public/index.html` | Output path for the home page                   |
+| `style_css`       | string/null | `null`            | CSS file copied next to rendered posts             |
+| `data_path`       | string      | `data.json`       | Path for the auto-generated post index             |
+
+## Post front matter
+
+Every Markdown post should start with a YAML front matter block:
+
+```yaml
+---
+title: Post Title          # required
+date: 2025-01-15           # used for ordering in index and RSS
+tags: [tag1, tag2]         # optional, passed to templates
+publish: public            # public | draft | unlisted
+maillist_title: ...        # optional, email comment link
+google_group_link: ...     # optional, link to mail thread
+---
+```
+
+**Visibility rules:**
+
+- `public` — appears in index and RSS
+- `draft` — skipped entirely (existing output is cleaned up)
+- `unlisted` — appears in RSS but not in the index
+
+## Templates
+
+The package ships with five default templates:
+
+| Template     | Purpose                         |
+|-------------|---------------------------------|
+| `header.html` | `<head>` block with CSS and RSS link |
+| `footer.html` | Footer with RSS link           |
+| `post.html`   | Single blog post page          |
+| `index.html`  | Post listing (all public posts)|
+| `home.html`   | Home / landing page             |
+
+Supply a `template_dir` in your config to override any of these. The templates
+use [Jinja2](https://jinja.palletsprojects.com/) syntax and receive variables
+like `heading`, `paragraphs`, `title`, `prev_post`, `next_post`, etc.
+
+## Bundled Lua filters
+
+| Filter       | Description                              |
+|-------------|------------------------------------------|
+| `gallery.lua` | Groups images in a paragraph into a responsive flex gallery |
+
+Enable with `gallery = true` in config, or pass `--gallery` on the CLI.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+## License
+
+MIT

essayist-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "essayist"
+version = "0.1.0"
+description = "A Pandoc + Jinja2 static site generator for Markdown blogs."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "ayx-dg" }]
+keywords = ["static-site-generator", "blog", "markdown", "pandoc", "jinja2"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Internet :: WWW/HTTP :: Site Management",
+]
+dependencies = [
+    "jinja2",
+    "pyyaml",
+    'tomli; python_version < "3.11"',
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.scripts]
+essayist = "essayist.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/ayx-dg/essayist"
+Repository = "https://github.com/ayx-dg/essayist"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+essayist = ["templates/*.html", "filters/*.lua", "style-note.css", "py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

essayist-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

essayist-0.1.0/src/essayist/__init__.py

@@ -0,0 +1,22 @@
+"""essayist: a Pandoc + Jinja2 static site generator.
+
+This package turns a directory of Markdown posts (with YAML front matter) into
+a static HTML site, an index page and an RSS feed.
+"""
+
+from __future__ import annotations
+
+from .builder import build_site
+from .config import Config
+from .core import Blog, pandoc, text_file_to_string
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Blog",
+    "Config",
+    "build_site",
+    "pandoc",
+    "text_file_to_string",
+    "__version__",
+]

essayist-0.1.0/src/essayist/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

essayist-0.1.0/src/essayist/builder.py

@@ -0,0 +1,58 @@
+"""High level build orchestration."""
+
+from __future__ import annotations
+
+import os
+import shutil
+
+from .config import Config
+from .core import Blog, text_file_to_string
+
+
+def build_site(config: Config) -> Blog:
+    """Run a full site build described by ``config`` and return the Blog."""
+    meta = {}
+    if config.blogname:
+        meta["blogname"] = config.blogname
+    if config.google_group_id:
+        meta["google_group_id"] = config.google_group_id
+
+    blog = Blog(
+        markdown_dir=config.markdown_dir,
+        post_dir=config.post_dir,
+        template_dir=config.template_dir,
+        meta=meta,
+        data_path=config.data_path,
+        site_url=config.site_url,
+    )
+    # set effective panargs (with bundled gallery filter if requested)
+    blog.default_panargs = config.effective_panargs(blog)
+
+    blog.update_data()
+    blog.build_posts()
+
+    if config.style_css:
+        dst_dir = os.path.dirname(os.path.join(config.post_dir, "style-note.css"))
+        os.makedirs(dst_dir, exist_ok=True)
+        shutil.copy2(config.style_css, os.path.join(config.post_dir, "style-note.css"))
+
+    if config.build_index:
+        blog.build_index(index_path=config.post_dir, index_title=config.index_title)
+
+    if config.build_rss:
+        rss_path = config.rss_path or os.path.join(config.post_dir, "rss.xml")
+        blog.build_rss(rss_path=rss_path)
+
+    if config.home_md:
+        home_html = blog.render_page(
+            content=text_file_to_string(config.home_md),
+            template_name=config.home_template,
+            meta={},
+            panargs=["--mathml"],
+        )
+        home_dir = os.path.dirname(config.home_output)
+        os.makedirs(home_dir, exist_ok=True)
+        with open(config.home_output, "w", encoding="utf-8") as f:
+            f.write(home_html)
+
+    return blog

essayist-0.1.0/src/essayist/cli.py

@@ -0,0 +1,90 @@
+"""Command line interface for the static site generator."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from dataclasses import fields
+
+try:  # Python >= 3.11
+    import tomllib
+except ModuleNotFoundError:  # Python 3.10
+    import tomli as tomllib
+
+from .builder import build_site
+from .config import Config
+
+
+def _load_config(path: str | None) -> Config:
+    """Load a :class:`Config` from a TOML file, if given."""
+    if not path:
+        return Config()
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+    # Accept either a top-level table or a [tool.essayist] table.
+    cfg = data.get("essayist", data)
+    known = {f.name for f in fields(Config)}
+    kwargs = {k: v for k, v in cfg.items() if k in known}
+    base = os.path.dirname(os.path.abspath(path))
+    config = Config(**kwargs)
+    config.resolve(base)
+    return config
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="essayist",
+        description="A Pandoc + Jinja2 static site generator.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_build = sub.add_parser("build", help="Build the static site.")
+    p_build.add_argument(
+        "-c", "--config", default="essayist.toml", help="Path to TOML config file."
+    )
+    p_build.add_argument("--markdown-dir", help="Directory with Markdown posts.")
+    p_build.add_argument("--post-dir", help="Output directory for posts.")
+    p_build.add_argument("--template-dir", help="Directory with Jinja2 templates.")
+    p_build.add_argument("--blogname", help="Blog name shown in page titles.")
+    p_build.add_argument("--site-url", help="Base URL used in RSS feeds.")
+    p_build.add_argument(
+        "--gallery", action="store_true", help="Enable the gallery lua filter."
+    )
+    p_build.set_defaults(func=_cmd_build)
+
+    sub.add_parser("version", help="Print the package version.").set_defaults(
+        func=_cmd_version
+    )
+    return parser
+
+
+def _cmd_build(args: argparse.Namespace) -> int:
+    config = _load_config(args.config)
+    # CLI flags override the config file.
+    for key in ("markdown_dir", "post_dir", "template_dir", "blogname", "site_url"):
+        value = getattr(args, key, None)
+        if value:
+            setattr(config, key, value)
+    if args.gallery:
+        config.gallery = True
+    build_site(config)
+    print("Build complete")
+    return 0
+
+
+def _cmd_version(args: argparse.Namespace) -> int:
+    from . import __version__
+
+    print(__version__)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())