Scraps Doc

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

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

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

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

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