Scraps Doc

#Deployment #Emit/Static Site Deploy a Scraps site to GitHub Pages using GitHub Actions. The build output (_site/ by default; configurable in Configuration#root-level) is uploaded as a Pages artifact and published via the official actions/deploy-pages action — no gh-pages branch required. GitHub settings Set up GitHub Pages for the repository. Build and deployment parameter as follows: Source: GitHub Actions Workflow file Prepare a YAML file under .github/workflows/ like this: name: Deploy scraps github pages on: push: branches: - main workflow_dispatch: permissions: contents: read concurrency: group: pages cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v6 with: fetch-depth: 0 # For scraps git committed date persist-credentials: false - name: Setup Scraps uses: boykush/scraps@v1 - name: Build run: scraps build - name: Configure Pages uses: actions/configure-pages@v5 - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: _site deploy: needs: build runs-on: ubuntu-latest permissions: pages: write id-token: write environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 The boykush/scraps action installs the matching CLI binary from GitHub Releases. Pin to a specific tag (@v1.0.0) or to a SHA with a version comment for Renovate-managed updates: - uses: boykush/scraps@<sha> # v1.0.0 If your output_dir differs from _site/, update the path: in the upload-pages-artifact step to match.

#Integration #Emit/CLI JSON Scraps integrates with AI assistants in two ways. CLI + JSON is the primary path because shell commands plus structured output are the lowest-friction contract any agent can use. MCP is supported for clients that expect Model Context Protocol tools. CLI + JSON (recommended) Any assistant with shell access can query Scraps without a long-running server. ❯ scraps search "rust cli" --logic and --json ❯ scraps get "Getting Started" --json ❯ scraps get "Getting Started" --heading "Install" --json body ❯ scraps get "Getting Started" --json code_blocks ❯ scraps get "Getting Started" --json images ❯ scraps links "Getting Started" --json ❯ scraps backlinks "Configuration" --json ❯ scraps tag list --json ❯ scraps todo --status all --json scraps get --json defaults to title, ctx, and body. It can project specific fields (title, ctx, body, headings, code_blocks, images) so an agent can avoid loading full bodies when it only needs structure or examples. scraps links --json returns outbound link and embed references with optional heading targets; backlinks stays a scrap-level inbound lookup. The full command map is in CLI Overview. Each command's --help documents flags and JSON shape. Bundled AI skills and agents For Claude Code and Codex users, the official scraps plugin packages Karpathy-style Ingest / Query / Lint workflows around the CLI. The Claude Code agents add purpose-driven lint handling and a default Scraps LLM Wiki schema grounded in the official docs: https://github.com/boykush/scraps/tree/main/plugins/scraps Skill / Agent Role /ingest Add a new scrap from a prompt, URL, or markdown; update cross-links /query Answer a question against the wiki with [[Title]] citations lint-rule-handler agent Purpose-driven wiki health checks, one or a few rules at a time scraps-llm-wiki-schema agent Explain Scraps tool usage from the official docs and map LLM Wiki practice to ingest, query, and lint-rule-handler Install instructions live in the plugin README so that marketplace browsers have everything in one place. MCP (for MCP-compatible clients) Scraps ships an MCP server for clients that prefer the Model Context Protocol. It serves over stdio by default, or over Streamable HTTP with --http so a single process can back every repository on your machine: ❯ scraps -C ~/path/to/your/wiki mcp serve --http This listens on 127.0.0.1:1113 and serves MCP at http://127.0.0.1:1113/mcp. Every repository points its client at that one URL, so the wiki path is configured once — on the server — instead of in each repository. One process serves one wiki; run a second process on another port to serve another. The server is bundled as a plugin so installation and tool specifications stay together: https://github.com/boykush/scraps/tree/main/plugins/mcp-server To register the running server with Claude Code manually, without the plugin: ❯ claude mcp add --transport http scraps http://127.0.0.1:1113/mcp For a single repository, stdio needs nothing running — the client spawns Scraps itself: ❯ claude mcp add scraps -- scraps -C ~/path/to/your/wiki mcp serve Replace ~/path/to/your/wiki with the directory containing .scraps.toml. For most read-shaped agent workflows, the CLI + JSON path above is simpler: nothing to keep running, no MCP client implementation required, works with any shell-capable agent. MCP is the right choice when your agent already expects MCP tools as its integration surface, and --http is the right transport when several repositories share one wiki.

#CLI This guide gets you from an empty directory to a small Scraps wiki that can be built as a static site and queried from the CLI. For the bigger picture of what Scraps is and why, see What is Scraps?. Setup Install Scraps — follow Installation. Initialize a project — create a directory and initialize it: ❯ mkdir my-knowledge-base ❯ cd my-knowledge-base ❯ scraps init This writes a .scraps.toml to the current directory. The directory containing it becomes the wiki root. Configure the project — open .scraps.toml and set [ssg] base_url and title. See Configuration#ssg-section for the full schema. Authoring Write Markdown files next to .scraps.toml or in folders under it. Standard CommonMark and GitHub-flavored Markdown are supported — see Markdown Support. Connect scraps with wiki-links. The full notation is in Wiki-link Notation; the most common forms are: [[Page Name]] — normal link [[Page Name|Display]] — alias [[Folder/Page Name]] — context-qualified [[Page Name#Heading]] — heading reference [[Page Name]] — embed another scrap inline #[[Topic]] — tag (separate namespace from scraps) #[[Area/Sub]] — nested tag (auto-aggregated) Build and preview ❯ scraps build # write _site/ ❯ scraps serve # serve at http://127.0.0.1:1112 The output structure, README.md handling, and search index are documented in Static Site. For deploying, see Deploy to GitHub Pages. Lint scraps lint checks wiki health: dead-end scraps, broken links, broken heading references, repeated links, and more. Rules are documented in Lint Rules. ❯ scraps lint AI integration Scraps is CLI-first for AI agents. Any assistant that can run shell commands can query the wiki: ❯ scraps search "query" --json ❯ scraps get "Page Name" --json ❯ scraps get "Page Name" --heading "Section" --json body ❯ scraps backlinks "Page Name" --json ❯ scraps todo --json scraps get --json returns title, ctx, and body by default. It can also project fields such as headings, code_blocks, or images, and --heading narrows the read to one section. For Claude Code users there is also an official skills bundle. See Integrate with AI Assistants for both paths.

#CLI After installing, see Getting Started for the basic flow. You can find the latest version on GitHub Releases. https://github.com/boykush/scraps/releases Requirements The git command is required for features. Cargo ❯ cargo install scraps macOS / Linux (Homebrew) ❯ brew install boykush/tap/scraps GitHub Releases Download the binary for your platform and place it in your PATH: # macOS (Apple Silicon) ❯ curl -sL https://github.com/boykush/scraps/releases/latest/download/scraps-aarch64-apple-darwin.tar.gz | tar xz # macOS (Intel) ❯ curl -sL https://github.com/boykush/scraps/releases/latest/download/scraps-x86_64-apple-darwin.tar.gz | tar xz # Linux (x86_64) ❯ curl -sL https://github.com/boykush/scraps/releases/latest/download/scraps-x86_64-unknown-linux-gnu.tar.gz | tar xz # Linux (ARM64) ❯ curl -sL https://github.com/boykush/scraps/releases/latest/download/scraps-aarch64-unknown-linux-gnu.tar.gz | tar xz Then move the binary to a directory in your PATH: ❯ sudo mv scraps /usr/local/bin/

#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 and SCRAPS_PROJECT_PATH were removed in v1.1 after one deprecated release. Use -C / --directory or the SCRAPS_DIRECTORY environment variable.

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

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