pipelines/songs

Publishes lyric pages from mikkeli/ncmr-songs to https://wiki.novoyuuparosk.org.

For the source-file contract (frontmatter and body conventions), see SCHEMA.md. This README covers the pipeline implementation and its runtime.

v1 scope

Implemented:

YAML frontmatter parsing per SCHEMA.md
Pandoc-based markdown → wikitext body rendering
First-line h1 stripping
Auto-generated banner + album category injection
MediaWiki bot API write with idempotency (no-op edits skipped)

Deferred (schema reserves the fields; renderer doesn't yet act on them):

LRC parsing and embedding
Inter-page sibling placeholder resolution
Multi-language metadata (the body conveys what languages exist; renderer doesn't introspect)
Auto-generated album index pages (intentionally NOT done — user writes album category-page descriptions freeform)

Invocation

The pipeline is invoked via a reusable Gitea Actions workflow (/.gitea/workflows/publish-songs.yml in this repo). The ncmr-songs repo holds a thin stub workflow that calls into this one on push to master.

Required environment at runtime:

Variable	Source	Purpose
`WIKI_API_URL`	Gitea variable	MediaWiki action API endpoint
`WIKI_BASE_URL`	Gitea variable	Wiki base URL (used in the banner link)
`WIKI_BOT_USER`	Gitea secret	Bot login (`Dubrowski@giteaAutomaton`)
`WIKI_BOT_PASSWORD`	Gitea secret	BotPasswords value
`SOURCE_DIR`	workflow input	Path to checked-out `ncmr-songs` working tree
`SOURCE_REF`	workflow input	The pushed-to commit SHA
`SOURCE_BASE_REF`	workflow input	The SHA prior to the push (for diff-based change detection)

Dependencies

Python 3.12+
Pandoc 2.x or newer (apt-installable in the runner container)
mwclient or requests for the MediaWiki API
PyYAML for frontmatter parsing
python-frontmatter (convenience wrapper around PyYAML for markdown frontmatter)

requirements.txt will be added when the implementation lands.

One-off wiki setup

Before the first run, two things must exist on the wiki:

Template:Auto-generated — the banner injected at the top of every auto-published page. Wikitext for this template is included in the implementation step (not yet written).
The bot user has edit rights for the namespace(s) the pipeline writes to. The default main namespace is fine; verify by attempting a manual edit via the bot account before relying on the pipeline.

Modes

The pipeline supports two invocation modes via the entry point:

Incremental (default, triggered by push): publishes only files changed between SOURCE_BASE_REF and SOURCE_REF.
Full (--all flag, triggered by workflow_dispatch): re-publishes every publishable file in the source tree. Use after template or renderer changes.

Not yet implemented

This README will grow as the pipeline does. Current commit ships only the schema and this overview — no executable code yet.

3.0 KiB Raw Blame History