Metadata-Version: 2.4
Name: araneus
Version: 0.1.0
Summary: A static site generator for multilingual sites.
Author-email: Mućka <mucka@mucka.pro>
License-Expression: Apache-2.0
Project-URL: Homepage, https://projects.mucka.pro/araneus/
Project-URL: Source, https://git.mucka.pro/projects/araneus
Project-URL: Changelog, https://git.mucka.pro/projects/araneus/tree/main/changelog.md
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown-it-py<5,>=4
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: pyyaml<7,>=6
Provides-Extra: dev
Requires-Dist: mypy<3,>=2.3; extra == "dev"
Requires-Dist: pytest<9,>=8.3; extra == "dev"
Requires-Dist: pytest-cov<8,>=7; extra == "dev"
Requires-Dist: ruff<1,>=0.11; extra == "dev"
Requires-Dist: types-PyYAML<7,>=6; extra == "dev"
Dynamic: license-file

# araneus

A static site generator for multilingual sites.

araneus is the fifth generation of the generator behind my website,
[mucka.pro](https://mucka.pro).
The earlier ones lived inside the site's own repository; this one is split
out, so the generator, the look, and the content each have a home of their
own.
I wanted it small and strict: plain directories of Markdown and YAML, a build
that refuses anything broken, and a deploy I can trace back to exact commits.
It is shared as it is, a personal tool that happens to be reusable.

## What it does

- Every article, note, or news item lives in its own directory, with its
  metadata in YAML and its text in CommonMark.
- Translations are separate entries linked into a group, and the language menu
  follows them.
- Series keep articles in order, and components make standalone pages such as
  a contact page.
- Stages from `idea` to `release` keep drafts out of the published site.
- Images, videos, and code listings become numbered figures that the text can
  reference.
- Every build checks XHTML, assets, and menu links, and keeps the previous
  output if anything fails.
- `serve` previews the site and reloads open pages when files change.
- `deploy` uploads with rsync and records the generator, layout, and site
  commits in `build.txt`.

The look of a site comes from a separate layout directory with Jinja2
templates, static files, and interface text, so one layout can serve several
sites.

## Install

araneus needs Python 3.14.

```sh
pip install araneus
```

## A first site

A site is a directory with a `site.yaml` and entries under `content/`, next
to a layout:

```text
layout/              templates, static files, languages.yaml
my-site/
├── site.yaml
└── content/
    └── 3f9a1c2e/    one entry, named by its mark
        ├── metadata.yaml
        └── main.md
```

The source distribution includes a complete example site and layout in
`examples/`; copy `examples/layout` to start with a working look.

`site.yaml` names the site and its layout:

```yaml
name: "My site"
layout: "../layout"
languages: ["en"]
default_language: "en"
base_url: "https://example.org"
copyright:
  holder: "Me"
  start_year: 2026
license:
  default: "CC-BY-4.0"
  known:
    CC-BY-4.0:
      name: "Creative Commons Attribution 4.0 International"
      url: "https://creativecommons.org/licenses/by/4.0/"
```

`araneus new` creates a draft article with a fresh mark, and `serve` shows it:

```sh
cd my-site
araneus new
araneus serve
```

Then open `http://localhost:8123/`.

## Documents

The [documents] directory has the full guides:

- `getting-started.md` builds and previews the example site.
- `user-guide.md` lists every command, option, and configuration key.
- `content-format.md` describes entries, metadata, Markdown, and figures.
- `deployment.md` covers deploy targets, `build.txt`, and the web server.
- `developer-guide.md` is for working on araneus itself.

Changes between versions are in the [changelog].

## License

araneus is licensed under Apache-2.0, see `LICENSE`.
Layouts and content keep their own licenses.

[documents]: https://git.mucka.pro/projects/araneus/tree/main/documents/
[changelog]: https://git.mucka.pro/projects/araneus/tree/main/changelog.md
