Scraps Doc

#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 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.

#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.

#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.

#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.

#Notation/Markdown Scraps compiles standard Markdown plus Wiki-link Notation. Authoring stays close to plain Markdown so files render correctly in any viewer; the typed [[…]] overlay adds compiler-enforced cross-references on top. CommonMark #Notation/Markdown Headings, paragraphs, lists, code blocks, links, and emphasis follow the CommonMark specification. The typed [[…]] overlay from Wiki-link Notation sits on top of this base layer. https://spec.commonmark.org/ GitHub-flavored Markdown #Notation/Markdown GitHub-flavored Markdown extensions are supported: tables, task lists, strikethrough, and autolinks. | Column | Column | |---|---| | cell | cell | - [x] done - [ ] open - [-] deferred ~~strikethrough~~ GFM task list items are aggregated wiki-wide by scraps todo (see CLI Overview). https://github.github.com/gfm/ Mermaid #Notation/Markdown Code blocks tagged mermaid render as Mermaid diagrams. This site uses one to show the compile pipeline. ```mermaid graph LR Source[Markdown sources] --> IR[Scraps IR] IR --> HTML[Static HTML] IR --> JSON[CLI JSON] ``` https://mermaid.js.org/intro/ Autolink with OGP card #Notation/Markdown Bare URLs wrapped in angle brackets render as OGP cards on the static site, fetching the target page's Open Graph metadata at build time. <https://github.com/boykush/scraps> The example above renders as a live OGP card on this page: https://github.com/boykush/scraps Use autolinks deliberately: the card is heavy compared to an inline link. Reach for <…> when the link is a "you should look at this" pointer (canonical source, prior art, recipe target). Use [text](url) for inline references that the reader skims past. The wiki root README.md falls back to plain links — see README and Index for the limitation.

#Configuration .scraps.toml declares a Scraps wiki: the directory containing this file is the wiki root, and every Markdown file under it is a scrap unless it lives in static/ or the configured output_dir. See What is Scraps? for why config discovery follows this shape, and CLI Overview for how -C selects between multiple .scraps.toml directories. Areas .scraps.toml has three areas: Area Purpose Required for Root level wiki-wide settings every command [ssg] static-site emit target build, serve [lint.*] opt-in lint rule config lint (only those rules) The [ssg] section is required only for build and serve; lint, tag, get, search, and mcp serve work without it. Within [ssg], base_url and title are required. Root level # Build output directory relative to this .scraps.toml (optional, default=_site) output_dir = "_site" # The site timezone (optional, default=UTC) timezone = "UTC" SSG section 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 Lint rules Opt-in rules read their config from [lint.<rule>]. Presence of the section enables the rule for scraps lint without requiring --rule. # Enables stale-by-git during `scraps lint`. [lint.stale_by_git] enabled = true threshold_days = 180 Default (graph-mechanical) rules are always on; see Lint Rules. Project Root Scraps does not use a scraps_dir setting in v1. To keep multiple independent wikis in one repository, place a separate .scraps.toml in each wiki directory and run commands with -C: ❯ scraps -C docs build ❯ scraps -C internal-wiki lint Each .scraps.toml is its own independent wiki — they do not cross-link, and each builds to its own output_dir. The old -p / --path flag is still accepted as a deprecated alias for one release. Prefer -C / --directory or the SCRAPS_DIRECTORY environment variable.

#CLI Wiki-link quality rules used by CLI Overview's lint command. Default rules are graph-mechanical (no external dependencies); rules with dependencies are opt-in via --rule or [lint.<rule>] in Configuration. Rule Detects Default dead-end scrap with no outbound links on lonely scrap with no backlinks on self-link scrap links to itself on overlinking same [[link]] repeated in one scrap on broken-link [[link]] that does not resolve on broken-heading-ref [[Page#Heading]] heading missing on stale-by-git last commit older than threshold (git-dependent) opt-in Output follows the cargo clippy-style diagnostic format. For LLM-driven purpose-based rule selection, see the lint-rule-handler agent in the scraps plugin.