constellate 0.3.6

Rust-powered CLI + live editor for curated markdown workspaces (requirements, docs, ADRs, audits, support, status-driven tasks) that build/serve/CRUD a themeable knowledge portal from a single binary.
constellate-0.3.6 is not a library.

Constellation Portal

Constellation Portal is a Rust-powered CLI and live editor that turns curated markdown workspaces—requirements, docs, ADRs, audits, support tickets, and status-driven task boards—into a themeable knowledge portal. Build, serve, validate, and CRUD everything from a single binary with configurable defaults and quick scaffolding for new documents.

Features

  • constellate build turns a workspace directory into a distributable static site (implementation placeholder for now).
  • constellate serve watches the workspace, rebuilds on changes, and serves the Material-themed portal with live reload (port configurable via --port and --no-watch to disable).
  • The generated home page includes a Material-styled task digest that surfaces in-progress, next-up, and recently finished tasks; tweak the number of entries via .constellate.toml (cards.task_summary_limit).
  • Sidebar navigation supports configurable collections per document type (status buckets with per-bucket limits) plus an optional "View all" drawer that reuses the search index for scoped browsing.
  • constellate status enforces per-type workflows (todo/ready/in-progress/done, etc.), updates front matter, and logs transitions under a ## Changes section.
  • constellate new scaffolds ADRs, tasks, or audits with sensible front matter, sequential IDs (based on configurable prefixes/widths), ID-prefixed slugified filenames (configurable globally or per document type), and a created: YYYY-MM-DD HH:MM:SS timestamp.
  • constellate validate checks markdown syntax (frontmatter structure, YAML validity) and validates internal links, with options for syntax-only or links-only checks and path filtering for targeted validation.
  • [document_types.list] can emit auto-generated list documents (an "all" view plus optional per-status partitions) and surface them as shortcuts at the top of the navigation sidebar.
  • constellate init bootstraps a brand-new workspace by creating workspace/pages with a welcome doc, a minimal .constellate.toml, and a .gitignore that ignores workspace/dist.
  • constellate theme list enumerates built-in layouts so teams can plan overrides, and constellate theme export copies the default templates into your workspace for customization.
  • constellate dump-config writes the default .constellate.toml so teams can override folders, document types, and templates.

Requirements

  • Rust 1.76+ with cargo.
  • Optional: Nix for reproducible shells (nix-shell nix/shell.nix).

Docker Usage

Prefer containers? The published image bundles only the constellate binary and exposes /workspace as a volume so you can mount any portal sources:

# Preview your local workspace with live reload on port 8080
docker run --rm -p 8080:8080 \
  -v "$PWD/workspace:/workspace" \
  onjin/constellate:0.3.2
  • Bind-mount a different path if your sources live elsewhere (-v "$PWD/my-docs:/workspace").
  • Override CLI flags as needed (for example ... constellate serve --input /workspace --output /workspace/dist --host 0.0.0.0 -p 8181 --no-watch).
  • When no volume is mounted the container starts with an empty /workspace; create or copy content into the mount before running the image.
  • Need write access for the in-browser editor? Either run as your host UID/GID (--user $(id -u):$(id -g)) or ensure the mounted directory is writable by the container user (chown the tree to the container UID or adjust permissions/ACLs).

Static Hosting via Nginx

After running constellate build, you can serve the generated workspace/dist with any static web server. This Dockerfile example uses the Constellate image for the build step and Nginx for hosting:

FROM onjin/constellate:0.3.2 AS builder
WORKDIR /workspace
COPY workspace/ /workspace/
RUN constellate build --input /workspace --output /workspace/dist

FROM nginx:1.25-alpine
COPY --from=builder /workspace/dist /usr/share/nginx/html

Build and run it:

docker build -t constellate-site .
docker run --rm -p 8080:80 constellate-site

Any time documents change, rerun constellate build (or rebuild the Docker image) so Nginx serves the updated static portal.

Nix Integration

  • nix run github:onjin/constellate executes the packaged CLI directly from the flake, while nix shell github:onjin/constellate drops the binary into a subshell.
  • nix develop github:onjin/constellate reuses nix/shell.nix so you can enter the development environment without cloning.
  • flake.nix exposes packages.constellate, an overlay, and dev shells so other flakes can inputs.constellate and reference self.packages.${system}.constellate.
  • NixOS systems can enable the CLI via imports = [ inputs.constellate.nixosModules.constellate ]; programs.constellate.enable = true;.
  • Home Manager users can import inputs.constellate.homeManagerModules.constellate and toggle programs.constellate.enable = true to add the binary to home.packages.
  • nix develop or nix flake check rely on the same shell definition used by nix-shell nix/shell.nix.

Shell Completions

  • Run constellate completion --shell bash > constellate.bash to generate a Bash completion script (other shells supported via --shell).
  • Source the generated script manually or drop it into your shell's completion directory.
  • The NixOS/Home Manager modules set enableBashIntegration = true by default, which enables Bash completion when you toggle programs.constellate.enable = true.

Contributing

Development workflow, template guard rails, and documentation expectations now live in CONTRIBUTING.md. Refer to that guide for cargo commands, template export instructions, and the renderer migration plan before opening a PR.

Project Layout

  • src/main.rs – clap-powered CLI entry point.
  • Cargo.toml – crate metadata and dependencies (clap, color-eyre).
  • nix/shell.nix – development environment definition.
  • workspace/pages/ – default document tree (requirements, docs, support, tasks, ADRs, audits, initiatives) that tracks Constellate itself and serves as the sample input for constellate build.
  • workspace/.constellate.toml – workspace-scoped configuration that maps document types to folders and points to the template overrides directory.
  • workspace/templates/ – optional override directory for Minijinja templates and partials referenced by the theme configuration.

Next Steps

  1. Extract the generator, status manager, and server utilities into dedicated modules with unit tests for markdown parsing, navigation rendering, and status transitions.
  2. Expand configuration loading so teams can define additional document types, status workflows, and dashboard cards without touching the binary.
  3. Implement theme discovery plus user asset overrides to complement the default Material skin. .constellate.toml also governs per-type status workflows and ID generation. Each [[document_types]] entry can define statuses = [...] plus id = { prefix = "REQ-", width = 3 } so constellate new always issues the next sequential identifier with consistent padding. Use the [portal] block to customize the site title/subtitle that appear in the header and hero (defaults to “Constellate Portal” / “Markdown → Material UI”).