Scraps Doc

#Notation/Wiki-link [[Title#Heading]] links to a specific heading inside another scrap. See [[Configuration#SSG section]] for the schema. If the target scrap exists but the heading does not match, Lint Rules reports broken-heading-ref. Heading text matches by slug, the same form the static site uses for fragment URLs.

#Notation/Wiki-link #[[tag]] marks a tag. Tags and scraps live in separate namespaces: a scrap named Markdown is reached via [[Markdown]], while the tag is #[[Markdown]]. This scrap is about #[[Markdown]] and #[[Notation/Wiki-link]]. Each tag has a generated index page on the static site — see Tag Pages.

#Notation/Wiki-link [[Title]] resolves by title within the wiki. See [[Getting Started]] for the basic flow. If the title does not resolve, Lint Rules reports a broken-link warning. Tags are a separate namespace and are not implicit fallback targets.

#Notation/Wiki-link [[Title|Display]] shows custom display text while linking to Title. [[Getting Started|the tutorial]] The plain form is Normal Link.

#Emit/Static Site The static site is one of the emit targets Scraps compiles to. The other first-class target is JSON from CLI Overview. See What is Scraps?#more-than-a-static-site-generator for why Scraps decenters SSG from its narrative while keeping the HTML output fully supported. Pipeline #Emit/Static Site graph LR Source[Markdown sources] --> IR[Scraps IR] IR --> HTML[Static HTML] IR --> JSON[CLI JSON] HTML --> Pages[GitHub Pages, Cloudflare Pages, ...] The HTML emitter takes the Scraps IR and produces a static directory tree, which any Pages-class host can serve. See Deploy to GitHub Pages for one such recipe. Output structure #Emit/Static Site Build output is written to the directory configured by output_dir (default _site/). ❯ tree _site _site ├── index.html # README.md or scrap index ├── scraps/ │ ├── getting-started.html │ └── guide/ │ └── links.html ├── main.css └── search_index.json # when build_search_index = true Each Markdown file is converted to a slugified HTML file under scraps/. Folders become path segments — the same folders that form Context Link. Files in static/ and the build output directory are excluded from scrap traversal. README and the index page #Emit/Static Site README.md at the wiki root is special-cased: it becomes index.html instead of scraps/readme.html. This lets the wiki render correctly both on the static site and directly on GitHub. One limitation: autolinks inside the wiki root README.md fall back to plain links — the OGP card is suppressed on the index page. Search index #Emit/Static Site When build_search_index = true (the default), the build emits search_index.json in the Fuse.js JSON shape and the static site mounts a search UI backed by it. [ { "title": "Getting Started", "url": "https://example.com/scraps/getting-started.html" }, { "title": "Configuration", "url": "https://example.com/scraps/configuration.html" } ] Search is scoped to the static site — it powers the in-page search box for human readers. Agent-side search is scraps search --json and is independent of this index. Set build_search_index = false in Configuration to skip both the index and the UI. Color scheme #Emit/Static Site The site adapts to the OS color scheme by default. Override the color_scheme field of [ssg] in Configuration: Value Behavior os_setting (default) Follow the user's OS preference only_light Force light only_dark Force dark Tag pages #Emit/Static Site Each #[[tag]] referenced by at least one scrap gets a generated index page listing all scraps that reference it. Nested tags (#[[a/b/c]]) auto-aggregate to their parents — see Nested Tag. Sort and pagination #Emit/Static Site The wiki index page is sorted by committed_date (default) or linked_count, and optionally paginated. Configure sort_key and paginate_by under [ssg] in Configuration. Configuration schema The full schema lives in Configuration ([ssg] and root level); the same [ssg] block is embedded below for in-place reading. Used by Static Site (HTML emit target). [ssg] # The site base url (required) base_url = "https://username.github.io/repository-name/" # The site title (required) title = "" # The site language (compliant with iso639-1, default=en) lang_code = "en" # The site description (optional) description = "" # The site favicon in the form of png file URL (optional) favicon = "" # The site color scheme # (optional, default=os_setting, choices=os_setting or only_light or only_dark) color_scheme = "os_setting" # Build a search index with the Fuse JSON and display search UI # (optional, default=true, choices=true or false) build_search_index = true # Scraps sort key choice on index page # (optional, default=committed_date, choices=committed_date or linked_count) sort_key = "committed_date" # Scraps pagination on index page (optional, default=no pagination) paginate_by = 20

#Emit/Static Site When build_search_index = true (the default), the build emits search_index.json in the Fuse.js JSON shape and the static site mounts a search UI backed by it. [ { "title": "Getting Started", "url": "https://example.com/scraps/getting-started.html" }, { "title": "Configuration", "url": "https://example.com/scraps/configuration.html" } ] Search is scoped to the static site — it powers the in-page search box for human readers. Agent-side search is scraps search --json and is independent of this index. Set build_search_index = false in Configuration to skip both the index and the UI.

#Emit/Static Site The wiki index page is sorted by committed_date (default) or linked_count, and optionally paginated. Configure sort_key and paginate_by under [ssg] in Configuration.

#Emit/Static Site graph LR Source[Markdown sources] --> IR[Scraps IR] IR --> HTML[Static HTML] IR --> JSON[CLI JSON] HTML --> Pages[GitHub Pages, Cloudflare Pages, ...] The HTML emitter takes the Scraps IR and produces a static directory tree, which any Pages-class host can serve. See Deploy to GitHub Pages for one such recipe.

#Emit/Static Site Build output is written to the directory configured by output_dir (default _site/). ❯ tree _site _site ├── index.html # README.md or scrap index ├── scraps/ │ ├── getting-started.html │ └── guide/ │ └── links.html ├── main.css └── search_index.json # when build_search_index = true Each Markdown file is converted to a slugified HTML file under scraps/. Folders become path segments — the same folders that form Context Link. Files in static/ and the build output directory are excluded from scrap traversal.