Metadata-Version: 2.4
Name: maatlog
Version: 0.1.0
Summary: A Sphinx extension that turns documentation projects into static blogs.
Author: usaturn
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Framework :: Sphinx :: Extension
Requires-Dist: sphinx>=9.1
Requires-Dist: myst-parser>=5.1
Requires-Dist: pydantic>=2
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/usaturn/maatlog
Description-Content-Type: text/x-rst

MaatLog
=======

MaatLog is a Sphinx extension that turns a documentation project into a static
blog. Posts are ordinary reStructuredText or MyST Markdown documents with a
small metadata schema. MaatLog adds archives, taxonomy navigation, Atom feeds,
and an HTML Theme API on top of Sphinx's public extension surface.

Requirements
------------

* Python 3.14+
* Sphinx 9.1+
* myst-parser 5.1+

Install
-------

From a built distribution (wheel or sdist)::

    pip install maatlog

Or from a checkout with `uv`::

    uv sync
    uv pip install -e .

Quick start
-----------

1. Enable the extension and (optionally) the bundled theme in ``conf.py``::

    extensions = ["maatlog"]

    html_theme = "maatlog-default"
    html_baseurl = "https://example.com/"  # required when Atom feeds are enabled

    maatlog_timezone = "UTC"
    maatlog_tags = {"sphinx": "Sphinx", "python": "Python"}
    maatlog_categories = {"engineering": "Engineering"}
    maatlog_authors = {"alice": "Alice"}

2. Write a reStructuredText post (field list before the title)::

    :maatlog-post: true
    :maatlog-published-at: 2026-08-01T09:00:00+09:00
    :maatlog-slug: hello-maatlog
    :maatlog-tags: sphinx, python
    :maatlog-categories: engineering
    :maatlog-authors: alice
    :maatlog-excerpt: First post with MaatLog.

    Hello MaatLog
    =============

    Body of the post…

3. Or an equivalent MyST Markdown post (YAML front matter)::

    ---
    maatlog-post: true
    maatlog-published-at: 2026-08-01T09:00:00+09:00
    maatlog-slug: hello-maatlog
    maatlog-tags: [sphinx, python]
    maatlog-categories: [engineering]
    maatlog-authors: [alice]
    maatlog-excerpt: First post with MaatLog.
    ---

    # Hello MaatLog

    Body of the post…

4. Build HTML::

    sphinx-build -b html sourcedir builddir

With the defaults above, MaatLog generates:

* Post pages using the selected MaatLog theme
* Archives under ``blog/`` (configurable via ``maatlog_archive_docname``)
* Atom feeds under the archive root (when ``maatlog_generate_feeds`` is true)
* Cross-reference roles such as ``:maatlog:post:``, ``:maatlog:tag:``, and friends

Rebuild notes
-------------

Most ``maatlog_*`` settings rebuild the Sphinx environment (``env``). Feed-related
settings rebuild HTML outputs only (``html``). After changing taxonomy
dictionaries, archive root, page size, timezone, or feed options, run a clean
or full rebuild so archives and feeds stay consistent.

``SOURCE_DATE_EPOCH`` (Unix seconds, UTC) freezes the build clock used for
draft / scheduled / expired publication status. Prefer it for reproducible CI
builds.

What MaatLog does not replace
-----------------------------

MaatLog does not replace Sphinx document titles, toctree, search, autodoc,
Pygments, or intersphinx. Ordinary documentation pages coexist with posts in
the same project. Full HTML features (archives, Theme API validation, feeds,
MaatLog HTML metadata) are guaranteed for the ``html`` and ``dirhtml`` builders
only; other builders keep post body and role resolution where applicable.

Documentation
-------------

* `docs/authoring.rst` — post metadata schema and examples
* `docs/configuration.rst` — conf.py settings and defaults
* `docs/theme-api.rst` — Theme API 1.0 contract and official themes
* `docs/builders.rst` — builder matrix and static-site constraints

Development
-----------

Node.js 24 is required only for contributor-side JavaScript and CSS quality
tooling. Installing and using the MaatLog Python package does not require
Node.js.

Official HTML and CSS support follows the ``browserslist`` query in
``package.json``. Long-tail browsers that still appear in ``defaults``
(Opera Mini, KaiOS 2.x, UC Browser, and QQ Browser) are out of scope.

Install both locked development environments and run the frontend checks::

    uv sync --locked --all-groups
    npm ci
    npm run check

The individual frontend commands are::

    npm run lint:js
    npm run format:check
    npm run typecheck:js
    npm run lint:css
    npm run format

The full verification profile runs browser-based accessibility tests, so
install the Playwright browser once before running it. On a system that also
needs the browser's OS packages, run the same command with ``--with-deps``
(it uses ``sudo``)::

    uv run playwright install chromium

The authoritative full repository verification remains::

    ./scripts/ci/verify.sh full

License and status
------------------

MaatLog MVP targets Sphinx-based static blogs. Development is still active
and the published package has no known users. Until the project stabilizes,
Theme API updates are breaking and do not keep older Theme API versions
working. Public metadata keys, config names, roles, generated docname
rules, and diagnostic codes remain compatibility-managed surfaces.
