lotek 0.2.0__tar.gz

lotek-0.2.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: lotek
+Version: 0.2.0
+Summary: A static site builder
+Author-email: Brad Arnett <brad.arnett@gmail.com>
+License: MIT
+Project-URL: Homepage, https://get.lotek.run
+Project-URL: Repository, https://github.com/lotek/lotek.run
+Keywords: static-site,builder,markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: tomli>=1.2; python_version < "3.11"
+Requires-Dist: markdown>=3.0
+Requires-Dist: pygments>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+
+# lotek.run
+
+A minimal static blog. Pandoc recommended; falls back to the `markdown` Python module if not available.
+
+## install
+
+Install the package:
+
+    pip install .
+
+Or install in development mode:
+
+    pip install -e .
+
+Then use the **lotek** command:
+
+Output goes to `output/`. Serve it with literally anything.
+
+## cli
+
+For day-to-day post management and operations, use the **lotek** command:
+
+    lotek init              Initialize a new site in the current directory
+    lotek build             Build the site
+    lotek clean             Remove build output
+    lotek serve [--port N]  Serve output locally (default: 8000)
+    lotek deploy            Build and deploy via rsync (reads .env)
+
+    lotek list              List all posts (formatted table)
+    lotek add "Title"       Create new post
+    lotek publish <slug>    Mark a post as published
+    lotek unpublish <slug>  Mark a post as unpublished
+
+All files are human-editable and can be edited directly.  It is recommended to preface your post files with a datecode, however it is not directly enforced.  Note that the `lotek add` command will automatically add a datecode to the title, as well as providing the frontmatter template needed to be recognized by the lotek command.
+
+It might seem weird that the only content editing command lotek exposes is "add".  But there's no need for any other tools, because we refuse to enforce their need.  With no dependencies come no obligations:
+
+Need to delete a file?  Use `rm`.  Need to search?  Use `grep -r`.  Want a UI?  Use an IDE like Sublime Text or VS Code.  Use Obsidian.  Don't like any of those options?  Roll your own.  The pieces are all here and exposed in plain view.
+
+## structure
+
+    content/posts/    markdown source files (YYYY-MM-DD-slug.md)
+    content/pages/    static pages (about.md, now.md, etc.)
+    templates/        html/xml templates
+    static/           css and any other static assets
+    output/           generated site (gitignored)
+
+## frontmatter
+
+Posts and pages share the same frontmatter schema:
+
+    ---
+    title: Post Title
+    date: YYYY-MM-DD
+    tags: tag1, tag2
+    publish: true
+    ---
+
+Set `publish: false` to suppress a file from the build without deleting it. `lotek publish` and `lotek unpublish` manage this field for posts.
+
+## pages
+
+Any `.md` file in `content/pages/` is built as a standalone page at `/<slug>.html`. Drop a file, wire up a nav link if you want it linked, done.
+
+    content/pages/about.md   →   /about.html
+    content/pages/now.md     →   /now.html
+
+`publish: false` in frontmatter suppresses the build, same as posts.
+
+## 404
+
+`output/404.html` is generated on every build with full site chrome. Point your server at it:
+
+- Apache: `ErrorDocument 404 /404.html`
+- nginx: `error_page 404 /404.html`
+
+## config
+
+Site settings live in `site-config.toml`:
+
+    [site.features]
+    robotstxt = true     # robots.txt + sitemap generation
+    rss = true           # RSS feed generation
+    skip_future = true   # exclude posts with dates > today
+
+    [site.rss]
+    limit = 10
+    timezone = "America/Los_Angeles"
+
+    [site.site]
+    title = "lotek.run"
+    url = "https://lotek.run"
+    description = "dispatches from the margins"
+
+    [[site.nav]]
+    label = "index"
+    href = "/"
+
+    [[site.nav]]
+    label = "about"
+    href = "/about.html"
+
+Nav links are ordered and fully configurable. Add, remove, or reorder `[[site.nav]]` blocks to change what appears in the header. If no nav is configured, the defaults (index, about, rss) are used.
+
+## deploy
+
+Set these in `.env` (see `.env.example`):
+
+    DEPLOY_USER=user
+    DEPLOY_HOST=example.com
+    DEPLOY_PATH=/var/www/html
+
+Then run `lotek deploy`.
+
+## automation
+
+I've set up automation via gitea runners personally, but that's out of scope of this project directly.  I recommend figuring it out on your own but if I get requests for tutorials I'll probably write about it.
+
+## philosophy
+
+No npm. No webpack. No framework. No build chain with a thousand dependencies ready to be poisoned upstream at any goddamn minute.
+Pandoc converts markdown to HTML. A Python script assembles pages from templates.
+The CSS is a flat file. Nothing requires Node.js. TA DA.
+
+## requirements
+
+Python 3.9+. Pandoc recommended; falls back to the `markdown` package if not found.
+
+If pandoc is not installed, install the fallback:
+
+    pip install markdown
+
+## getting started
+
+    mkdir mysite && cd mysite
+    lotek init
+    # edit site-config.toml with your title/url
+    lotek build
+    lotek serve

lotek-0.2.0/README.md

@@ -0,0 +1,139 @@
+# lotek.run
+
+A minimal static blog. Pandoc recommended; falls back to the `markdown` Python module if not available.
+
+## install
+
+Install the package:
+
+    pip install .
+
+Or install in development mode:
+
+    pip install -e .
+
+Then use the **lotek** command:
+
+Output goes to `output/`. Serve it with literally anything.
+
+## cli
+
+For day-to-day post management and operations, use the **lotek** command:
+
+    lotek init              Initialize a new site in the current directory
+    lotek build             Build the site
+    lotek clean             Remove build output
+    lotek serve [--port N]  Serve output locally (default: 8000)
+    lotek deploy            Build and deploy via rsync (reads .env)
+
+    lotek list              List all posts (formatted table)
+    lotek add "Title"       Create new post
+    lotek publish <slug>    Mark a post as published
+    lotek unpublish <slug>  Mark a post as unpublished
+
+All files are human-editable and can be edited directly.  It is recommended to preface your post files with a datecode, however it is not directly enforced.  Note that the `lotek add` command will automatically add a datecode to the title, as well as providing the frontmatter template needed to be recognized by the lotek command.
+
+It might seem weird that the only content editing command lotek exposes is "add".  But there's no need for any other tools, because we refuse to enforce their need.  With no dependencies come no obligations:
+
+Need to delete a file?  Use `rm`.  Need to search?  Use `grep -r`.  Want a UI?  Use an IDE like Sublime Text or VS Code.  Use Obsidian.  Don't like any of those options?  Roll your own.  The pieces are all here and exposed in plain view.
+
+## structure
+
+    content/posts/    markdown source files (YYYY-MM-DD-slug.md)
+    content/pages/    static pages (about.md, now.md, etc.)
+    templates/        html/xml templates
+    static/           css and any other static assets
+    output/           generated site (gitignored)
+
+## frontmatter
+
+Posts and pages share the same frontmatter schema:
+
+    ---
+    title: Post Title
+    date: YYYY-MM-DD
+    tags: tag1, tag2
+    publish: true
+    ---
+
+Set `publish: false` to suppress a file from the build without deleting it. `lotek publish` and `lotek unpublish` manage this field for posts.
+
+## pages
+
+Any `.md` file in `content/pages/` is built as a standalone page at `/<slug>.html`. Drop a file, wire up a nav link if you want it linked, done.
+
+    content/pages/about.md   →   /about.html
+    content/pages/now.md     →   /now.html
+
+`publish: false` in frontmatter suppresses the build, same as posts.
+
+## 404
+
+`output/404.html` is generated on every build with full site chrome. Point your server at it:
+
+- Apache: `ErrorDocument 404 /404.html`
+- nginx: `error_page 404 /404.html`
+
+## config
+
+Site settings live in `site-config.toml`:
+
+    [site.features]
+    robotstxt = true     # robots.txt + sitemap generation
+    rss = true           # RSS feed generation
+    skip_future = true   # exclude posts with dates > today
+
+    [site.rss]
+    limit = 10
+    timezone = "America/Los_Angeles"
+
+    [site.site]
+    title = "lotek.run"
+    url = "https://lotek.run"
+    description = "dispatches from the margins"
+
+    [[site.nav]]
+    label = "index"
+    href = "/"
+
+    [[site.nav]]
+    label = "about"
+    href = "/about.html"
+
+Nav links are ordered and fully configurable. Add, remove, or reorder `[[site.nav]]` blocks to change what appears in the header. If no nav is configured, the defaults (index, about, rss) are used.
+
+## deploy
+
+Set these in `.env` (see `.env.example`):
+
+    DEPLOY_USER=user
+    DEPLOY_HOST=example.com
+    DEPLOY_PATH=/var/www/html
+
+Then run `lotek deploy`.
+
+## automation
+
+I've set up automation via gitea runners personally, but that's out of scope of this project directly.  I recommend figuring it out on your own but if I get requests for tutorials I'll probably write about it.
+
+## philosophy
+
+No npm. No webpack. No framework. No build chain with a thousand dependencies ready to be poisoned upstream at any goddamn minute.
+Pandoc converts markdown to HTML. A Python script assembles pages from templates.
+The CSS is a flat file. Nothing requires Node.js. TA DA.
+
+## requirements
+
+Python 3.9+. Pandoc recommended; falls back to the `markdown` package if not found.
+
+If pandoc is not installed, install the fallback:
+
+    pip install markdown
+
+## getting started
+
+    mkdir mysite && cd mysite
+    lotek init
+    # edit site-config.toml with your title/url
+    lotek build
+    lotek serve

lotek-0.2.0/lotek/__init__.py

@@ -0,0 +1,13 @@
+"""lotek.run - A static site builder."""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("lotek-run")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+import lotek.cli as cli
+
+def main():
+    cli.main()

lotek-0.2.0/lotek/build.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""lotek.run -- static site builder
+
+Requires: pandoc in PATH or markdown module
+"""
+
+from lotek.lib.site_config import config
+from lotek.lib.site_time import now_string
+from lotek.lib.pages import generate_pages
+from lotek.lib.posts import generate_posts, load_posts
+from lotek.lib.index import generate_index_landing
+from lotek.lib.dirs import dirs
+from lotek.lib.static import wipe_and_copy_to_output_dir
+from lotek.plugins.rss import generate_rss
+from lotek.plugins.robots import generate_robots
+
+
+def build():
+    """main entry point"""
+
+    out = dirs.OUTPUT
+    print(f"building lotek at {out}")
+    out.mkdir(exist_ok=True)
+    dirs.OUTPUT_POSTS.mkdir(exist_ok=True)
+    dirs.OUTPUT_STATIC.mkdir(exist_ok=True)
+    posts = load_posts(dirs.CONTENT_POSTS)
+
+    generate_posts(posts, out)
+    generate_pages(out)
+    if config.features.robotstxt:
+        print("generating robots.txt...")
+        generate_robots(posts, out)
+    if config.features.rss:
+        print("generating RSS feed...")
+        generate_rss(posts, out)
+    generate_index_landing(posts, out)
+    wipe_and_copy_to_output_dir(out)
+
+    print(f"built {len(posts)} posts -> output/")
+    last_file = out / "_last"
+    last_file.write_text(now_string())

lotek-0.2.0/lotek/cli.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""lotek - operational command for lotek.run."""
+import sys
+import argparse
+from pathlib import Path
+import lotek
+
+from lotek.lib.init import init
+from lotek.cmd.add import cmd_add
+from lotek.cmd.build import cmd_build
+from lotek.cmd.clean import cmd_clean
+from lotek.cmd.deploy import cmd_deploy
+from lotek.cmd.list import cmd_list
+from lotek.cmd.publish import cmd_publish, cmd_unpublish
+from lotek.cmd.serve import cmd_serve
+
+USAGE = f"""
+lotek - Tiny Blog Management Tool
+ver: {getattr(lotek, "__version__", "unknown")}
+
+Build:
+  lotek build             Build the site
+  lotek clean             Remove build output
+  lotek serve [--port N]  Serve output locally (default: 8000)
+  lotek deploy            Build and deploy via rsync (reads .env)
+
+Content:
+  lotek init              Make a new site from scratch
+  lotek list              List all posts
+  lotek add <title>       Create new post
+  lotek publish <slug>    Mark a post as published
+  lotek unpublish <slug>  Mark a post as unpublished
+"""
+
+def setup_cmd_parser():
+    parser = argparse.ArgumentParser(prog="lotek")
+    subs = parser.add_subparsers(dest="command")
+
+    i = subs.add_parser("init")
+    i.add_argument("path", type=str, default=".", nargs="?")
+
+    subs.add_parser("build")
+
+    subs.add_parser("clean")
+
+    p = subs.add_parser("serve")
+    p.add_argument("--port", "-p", type=int, default=8000)
+
+    p = subs.add_parser("deploy")
+    p.add_argument("--skip-build", action="store_true")
+
+
+    subs.add_parser("list")
+
+    p = subs.add_parser("add")
+    p.add_argument("title", nargs="?")
+
+    p = subs.add_parser("publish")
+    p.add_argument("slug")
+
+    p = subs.add_parser("unpublish")
+    p.add_argument("slug")
+
+    args = parser.parse_args()
+    return args
+
+def main():
+    args = setup_cmd_parser()
+    if not args.command:
+        print(USAGE)
+        return 0
+    try:
+        if args.command == "init":
+            return init(Path.absolute(Path(args.path)))
+        if args.command == "build":
+            return cmd_build()
+        if args.command == "clean":
+            return cmd_clean()
+        if args.command == "serve":
+            return cmd_serve(args.port)
+        if args.command == "deploy":
+            return cmd_deploy(skip_build=args.skip_build)
+        if args.command == "list":
+            return cmd_list()
+        if args.command == "add":
+            return cmd_add(args.title)
+        if args.command == "publish":
+            return cmd_publish(args.slug)
+        if args.command == "unpublish":
+            return cmd_unpublish(args.slug)
+    except KeyboardInterrupt:
+        print("\nInterrupted")
+        return 1
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+if __name__ == "__main__":
+    main()

lotek-0.2.0/lotek/cmd/add.py

@@ -0,0 +1,25 @@
+from datetime import datetime
+from lotek.lib.colors import red, green
+from lotek.lib.dirs import dirs
+
+def cmd_add(title):
+    if not title:
+        print(red("Title required"))
+        return 1
+    posts_dir = dirs.CONTENT_POSTS
+    posts_dir.mkdir(parents=True, exist_ok=True)
+    today = datetime.now().strftime("%Y-%m-%d")
+    slug = title.lower().replace(" ", "-")
+    fname = f"{today}-{slug}.md"
+    fp = posts_dir / fname
+    if fp.exists():
+        print(red(f"Already exists: {fname}"))
+        return 1
+    template_path = dirs.TEMPLATES / "post.md"
+    if not template_path.exists():
+        print(red("Templates not found — run 'lotek init' first"))
+        return 1
+    template = template_path.read_text()
+    fp.write_text(template.replace("{title}", title).replace("{date}", today))
+    print(green(f"Created: content/posts/{fname}"))
+    return 0

lotek-0.2.0/lotek/cmd/build.py

@@ -0,0 +1,12 @@
+import sys
+from lotek.lib.colors import red
+import lotek.build as build_module
+
+def cmd_build():
+
+    try:
+        build_module.build()
+        return 0
+    except Exception as e:
+        print(red(f"Build failed: {e}"), file=sys.stderr)
+        return 1

lotek-0.2.0/lotek/cmd/clean.py

@@ -0,0 +1,12 @@
+
+import shutil
+from lotek.lib.colors import green
+from lotek.lib.dirs import dirs
+
+def cmd_clean():
+
+    output = dirs.OUTPUT
+    if output.exists():
+        shutil.rmtree(output)
+        print(green("Removed output/"))
+    return 0

lotek-0.2.0/lotek/cmd/deploy.py

@@ -0,0 +1,52 @@
+import subprocess
+
+from lotek.lib.colors import green, red
+from lotek.lib.dirs import dirs
+from lotek.cmd.build import cmd_build
+
+def read_env():
+    env_path = dirs.CWD / ".env"
+    if not env_path.exists():
+        return {}
+    env = {}
+    for line in env_path.read_text().splitlines():
+        if "=" in line and not line.startswith("#"):
+            k, _, v = line.partition("=")
+            env[k.strip()] = v.strip()
+    return env
+
+
+def cmd_deploy(skip_build=False):
+    env = read_env()
+    user, host, path = (
+        env.get("DEPLOY_USER"),
+        env.get("DEPLOY_HOST"),
+        env.get("DEPLOY_PATH"),
+    )
+    if not all([user, host, path]):
+        print(red("Missing DEPLOY_USER, DEPLOY_HOST, or DEPLOY_PATH in .env"))
+        return 1
+    if not skip_build:
+        print(green("Building..."))
+        rc = cmd_build()
+        if rc != 0:
+            return rc
+    dest = f"{user}@{host}:{path}/"
+    print(green(f"Deploying to {dest}"))
+    result = subprocess.run(
+        [
+            "rsync",
+            "-avz",
+            "--exclude=.env",
+            "--exclude=*.pyc",
+            "--exclude=__pycache__",
+            "--exclude=output",
+            "output/",
+            dest,
+        ]
+    )
+    if result.returncode != 0:
+        print(red("Deploy failed"))
+        return result.returncode
+    print(green("Deployed successfully"))
+    return 0

lotek-0.2.0/lotek/cmd/list.py

@@ -0,0 +1,57 @@
+from datetime import datetime
+
+from lotek.lib.site_config import config
+from lotek.lib.dirs import dirs
+from lotek.lib.frontmatter import parse_frontmatter
+from lotek.lib.colors import green, BOLD, RESET
+
+def _table(headers, rows):
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, c in enumerate(row):
+            widths[i] = max(widths[i], len(str(c)))
+    hdr = "│ " + " │ ".join(h.center(w) for h, w in zip(headers, widths)) + " │"
+    print(BOLD + hdr + RESET)
+    print("-" * len(hdr))
+    for row in rows:
+        print("│ " + " │ ".join(str(c).ljust(w) for c, w in zip(row, widths)) + " │")
+
+def cmd_list():
+    posts_dir = dirs.CONTENT_POSTS
+    if not posts_dir.exists():
+        print("No posts directory found")
+        return 0
+    today = datetime.now().date()
+    posts = []
+    for f in posts_dir.glob("*.md"):
+        meta, _ = parse_frontmatter(f.read_text())
+        if meta.get("title"):
+            posts.append((f, meta))
+    if not posts:
+        print("No posts found")
+        return 0
+
+    def sort_key(item):
+        try:
+            return datetime.strptime(item[1].get("date", ""), "%Y-%m-%d").date()
+        except ValueError:
+            return today
+
+    posts.sort(key=sort_key, reverse=True)
+    rows = []
+    for f, meta in posts:
+        date_str = meta.get("date", "")
+        if meta.get("publish", "").lower() == "false":
+            state = "hidden"
+        elif config.features.skip_future:
+            try:
+                d = datetime.strptime(date_str, "%Y-%m-%d").date()
+                state = f"in {(d - today).days}d" if d > today else "live"
+            except ValueError:
+                state = "live"
+        else:
+            state = "live"
+        rows.append([date_str, meta.get("title", ""), f.stem, state])
+    print(green(f"{len(posts)} post(s)"))
+    _table(["date", "title", "slug", "status"], rows)
+    return 0

lotek-0.2.0/lotek/cmd/publish.py

@@ -0,0 +1,63 @@
+import sys
+
+from lotek.lib.frontmatter import parse_frontmatter
+from lotek.lib.colors import green, red
+from lotek.lib.dirs import dirs
+
+def _strip_datecode(stem):
+    if (
+        len(stem) > 11
+        and stem.startswith("20")
+        and stem[4] == stem[7] == "-"
+        and stem[10] == "-"
+    ):
+        return stem[11:]
+    return stem
+
+def find_post(slug):
+    posts_dir = dirs.CONTENT_POSTS
+    if not posts_dir.exists():
+        return None
+    fp = posts_dir / f"{slug}.md"
+    if fp.exists():
+        return fp
+    for f in posts_dir.glob("*.md"):
+        if slug == _strip_datecode(f.stem):
+            return f
+    matches = [
+        f for f in posts_dir.glob("*.md") if _strip_datecode(f.stem).startswith(slug)
+    ]
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        print(red(f"Ambiguous: {len(matches)} matches for '{slug}'"))
+        for m in matches:
+            print(f"  {m.stem}")
+        sys.exit(2)
+    return None
+
+def _set_publish(slug, value):
+    fp = find_post(slug)
+    if not fp:
+        print(red(f"Not found: {slug}"))
+        return 1
+    meta, body = parse_frontmatter(fp.read_text())
+    if not meta.get("title"):
+        print(red("No title in frontmatter"))
+        return 1
+    meta["publish"] = value
+    fp.write_text(
+        "---\n" + "".join(f"{k}: {v}\n" for k, v in meta.items()) + "---\n\n" + body
+    )
+    print(green(f"{'Published' if value == 'true' else 'Unpublished'}: {slug}"))
+    return 0
+
+
+def cmd_publish(slug):
+    """ i don't know if we even need these, really."""
+    return _set_publish(slug, "true")
+
+
+def cmd_unpublish(slug):
+    """ i don't know if we even need these, really."""
+    return _set_publish(slug, "false")