Scraps Doc

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

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

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

#Notation/Wiki-link Wiki-link notation gives Markdown a typed surface: each [[…]] is a typed reference that the compiler can resolve, lint, and emit. See What is Scraps?#markdown-as-typed-source for the design rationale. Normal link #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. Alias #Notation/Wiki-link [[Title|Display]] shows custom display text while linking to Title. [[Getting Started|the tutorial]] The plain form is Normal Link. Context-qualified link #Notation/Wiki-link [[Ctx/Title]] resolves a scrap whose title is shared with another in a different folder. [[DDD/Service]] [[Kubernetes/Service]] Context-qualified links resolve from the wiki root, not relative to the linking scrap. Context depth is bounded at 3 segments. Combine with Alias when you want a different display text. Heading reference #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. Embed #Notation/Wiki-link [[Title]] inlines another scrap's body at this location. Embeds remove duplication when two pages need to show the same content. [[Getting Started]] For embedding only one section, see Section Embed. Section embed #Notation/Wiki-link [[Title#Heading]] embeds a single section from another scrap. [[Configuration#SSG section]] This is how this site keeps the [ssg] schema authoritative in Configuration while Static Site surfaces the same block — exactly one source of truth. Tag #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. Nested tag #Notation/Wiki-link #[[a/b/c]] is a nested tag with max depth 3. Nested tags auto-aggregate Logseq-style: #[[Notation/Wiki-link]] and #[[Notation/Markdown]] both surface under the #[[Notation]] index. #[[Emit/Static Site]] #[[Emit/CLI JSON]] Each tag (and each parent in the hierarchy) gets its own page on the static site — see Tag Pages. Resolution rules Title match. [[name]] resolves by exact title against scraps in the wiki. Ambiguity is an error. If [[Service]] could match DDD/Service.md or Kubernetes/Service.md, the build / lint fails with a resolution error. Tags do not fall back. A [[name]] that does not match a scrap is always broken-link, even if a #[[name]] tag exists. Heading match. [[Title#Heading]] matches by slug against the target's rendered headings.

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

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

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

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

#CLI Scraps is a CLI-first compiler. Every command supports --help, which is the authoritative reference for flags and arguments. This page is the map. Command Role --json scraps init Write .scraps.toml to the current directory – scraps build Compile to the _site/ static site – scraps serve Build then serve at http://127.0.0.1:1112 – scraps lint Wiki-link health check (Lint Rules) – scraps get <title> Single-scrap introspection ✓ scraps search <query> Fuzzy search over titles + body ✓ scraps links <title> Outbound wiki-links from a scrap ✓ scraps backlinks <title> Inbound wiki-links to a scrap ✓ scraps tag list List all tags with backlink counts ✓ scraps tag backlinks <tag> Scraps referencing a tag ✓ scraps todo Aggregate GFM task list items wiki-wide ✓ scraps mcp serve Start an MCP server over stdio, or --http – -C / --directory (or SCRAPS_DIRECTORY env) runs as if started in the given directory. JSON Reads scraps get reads one scrap, optionally scoped by context and heading: scraps get "Title" --ctx "Book" --heading "Install" --json Its --json flag accepts an optional comma-separated field projection. With no projection it returns title, ctx, and body. scraps get "Title" --json title,ctx,body scraps get "Title" --json code_blocks scraps get "Title" --json images scraps get "Title" --heading "Install" --json body,headings Allowed fields are title, ctx, body, headings, code_blocks, and images. Reference navigation stays separate: use scraps links, scraps backlinks, and scraps tag .... scraps links --json returns outbound reference occurrences. Each result has kind (link or embed), title, ctx, and heading, so agents can jump directly to scraps get <title> --ctx <ctx> --heading <heading>. scraps backlinks --json remains scrap-level inbound discovery and returns the scraps that link to the requested scrap. For agent integration, see Integrate with AI Assistants.