Skip to content

rc-glue.sh

Generate navigation glue (index.md) for unindexed directories

Browse Docs pages

Overview

Generate navigation glue (index.md) for unindexed directories

Source: bones/scripts/rc-glue.sh.

Usage

rotkeeper.sh glue [options]

Options

--path DIR       Limit glue to a directory under home/content/
--force          Refresh existing auto-generated indexes
--dry-run        Preview changes without writing
--verbose        Show detailed logs
--help, -h       Show this help message
--version, -v    Show script version and quit

Examples

bash rotkeeper.sh glue                                # Glue all unindexed directories
bash rotkeeper.sh glue --path journal                 # One directory
bash rotkeeper.sh glue --force --dry-run              # Preview refresh

Exit codes

0    Success
1    Generation failure

Reads and writes

Environment: reads BONES_DIR, CONFIG_DIR, CONTENT_DIR, DOCS_DIR, DRY_RUN, LOG_DIR, META_DIR, QUIET, ROOT_DIR, SCRIPT_DIR, TMP_DIR, VERBOSE (canonical via rc-env.sh / rk_load_env); overrides RK_OLIVER_BIN, RK_RENDERER, ROTKEEPER_VERSION when set.

Working directory: No CWD assumption — all paths are root-relative via ROOT_DIR/BONES_DIR/CONTENT_DIR/etc. derived from rc-env.sh; helpers rk_canonical_path/rk_canonical_or_raw resolve symlinks/portably.

Inputs and outputs: reads directories and immediate .md, .textile, and .cook children under CONTENT_DIR, or a canonicalized --path subtree. Requires yq v4+ and GNU awk; destinations outside the content boundary are rejected. Creates missing index.md files using the resolved default template and directory-sidecar frontmatter, with child links between ROTKEEPER-GLUE-START/END markers. Generated indexes carry rotkeeper_glued: true; --force removes and regenerates only those marked indexes. Custom indexes keep their authored prose. An ordered single marker pair is replaced through a temporary file; otherwise glue is appended. Rewrite failures preserve the original. Dry-run previews writes without changing indexes.

Side effects

Notes

Design

Walks the active content tree, or a canonicalized subtree selected by --path, and creates missing index.md sources with links to immediate directories and Markdown, Textile, and Cooklang children. Default template selection uses the shared resolver. Directory-sidecar frontmatter overrides default metadata. A sidecar with nonempty target_file is a file sidecar and is not merged into an index, including the dispatcher sidecar at the content-root lookup path bones/meta/rotkeeper.soul.md.

Limits

Existing indexes marked rotkeeper_glued: true are skipped unless forced. Custom indexes keep their frontmatter and prose; exactly one ordered glue-marker pair is replaced, while missing or ambiguous markers cause a new block to be appended. Marker recognition and the generated-index test are textual, not a structural Markdown/frontmatter parse. Links assume each child directory has an index and do not verify rendered destinations.

Cautions

--force removes a marked generated index before recreating it, so manual edits in that file are lost and regeneration is not an atomic replacement. Custom-block replacement uses a temporary file and keeps the original on rewrite failure. Glue is inserted as literal environment data into gawk, not regex replacement text. Dry-run skips index mutations but still performs metadata/template resolution and writes bootstrap logs.

History

[0.4.1] - 2026-07-22

[0.3.0.9] - 2026-06-15