Styled Markdown 2.5.0

Downloads

Asset	What it is	How to install
styled-markdown-2.5.0.vsix	VS Code extension	code --install-extension styled-markdown-2.5.0.vsix, or Extensions → ⋯ → Install from VSIX… (guide)
styled-markdown-2.5.0.tgz	npm package (library + smd CLI), the same file as on npm	npm install -g ./styled-markdown-2.5.0.tgz
styled-markdown-writer.zip	Agent skill: create and edit .smd following the rules	Unzip into ~/.claude/skills/ or upload in Claude → Settings → Capabilities → Skills (guide)
styled-markdown-reader.zip	Agent skill: token-efficient reading	Same as above
styled-markdown-playground.zip	Web playground: edit, preview and share .smd in the browser	Unzip and open playground/index.html, or serve the folder (guide)
mkdocs_styled_markdown-2.5.0-py3-none-any.whl	MkDocs plugin (Python wheel; needs Node.js 22+)	pip install ./mkdocs_styled_markdown-2.5.0-py3-none-any.whl (guide)
mkdocs_styled_markdown-2.5.0.tar.gz	MkDocs plugin source distribution	pip install ./mkdocs_styled_markdown-2.5.0.tar.gz
styled-markdown-obsidian-2.5.0.zip	Obsidian plugin (a styled-markdown folder with main.js, manifest.json and styles.css)	Unzip into your vault's .obsidian/plugins/, then turn it on in Settings → Community plugins (guide)
styled-markdown-jetbrains-2.5.0.zip	JetBrains plugin (IntelliJ IDEA 2025.3+, PyCharm, WebStorm…): highlighting and the language server; needs Node.js 22+	Settings → Plugins → ⚙ → Install Plugin from Disk… (guide)

Built for developers who use AI coding agents. One command sets an agent up (smd init --agent, or the new Claude Code plugin); smd read reads a document in one call; and the tools now cost less than they save: the MCP tool list, the reader skill and the agent rules are 63–79% smaller. Also new: opt-in MCP write tools, smd savings, a net-tokens benchmark, spec → plan → tasks templates, a compatibility policy that declares spec v2 stable, and community files. No breaking changes: documents, commands, flags, settings, skills and library exports from 2.4.0 keep working, and the MCP tools outline, section and agent still answer when called.

Added

• smd read <file>: one call to start reading a document. It prints the whole agent view when it fits 2,000 tokens (--max-tokens <n> sets the budget) and otherwise the outline, so an agent no longer needs smd outline and then smd agent. --section (repeatable) reads only those sections, --outline and --full force one form, and --brief and --no-lines work as on smd agent.

• MCP read tool. The same as smd read, with sections, mode (auto, outline, full) and brief.

• smd init --agent claude|cursor|copilot|agents: set up an agent in one command. It installs the skills (claude) or the reading and writing rules (cursor, copilot, agents for AGENTS.md), the CLI, and the MCP server in the agent's own config: .mcp.json (Claude Code), .cursor/mcp.json (Cursor) or .vscode/mcp.json (Copilot in VS Code). Existing config files are merged and other servers kept; a file with comments is left alone and the entry to add is printed. Re-run it to update; --dir <project> picks the project and --no-mcp skips the MCP config. The npm package gets a styled-markdown command for it, so npx styled-markdown init --agent claude works once the package is on npm.

• Opt-in MCP write tools: smd mcp --allow-write. check_task ticks or unticks one task (by the line tasks prints, optionally checking the line still has the expected text), set_status sets the front matter status (and updated when there is one), and add_decision appends a :::decision block to a section. Each changes only its own lines, keeps line endings, stays inside --root, and writes nothing when the result would have more validation errors than before. Without the flag the server stays read-only.

• smd savings <files|dirs…>: what the agent view saves across a repository. Tokens per document for the raw file, the agent view and --brief, the total saving and its price in dollars (--price, USD per million input tokens, default 3), and --json for tools. On this repository's examples/ it reports 25% (31% with --brief) for reading every document whole; reading only the needed sections saves more.

• Net-tokens benchmark. npm run bench:tokens (in extension/) shows how many tokens an agent spends on each example. It covers two tasks, answering about one section and understanding the whole document, and compares a plain read of the file with outline + section, smd read, the agent view and --brief. The count includes the tools' own fixed cost: skill descriptions, the reader SKILL.md, agent rules and the MCP tool list, all read at run time. A key-line coverage check stands in for accuracy. The output ends with break-even document sizes. docs/TOKENS.md explains the method and has the results.

• Reader skill reference. styled-markdown-reader/references/reading.md holds what the slimmer SKILL.md left out: every marker of the agent view, the commands for many documents, the MCP tools and reading without Node.js. Agents read it only when they need it. smd skills install installs it.

• Claude Code plugin: the repository is a plugin marketplace. /plugin marketplace add bislink360/styled-markdown, then /plugin install styled-markdown@styled-markdown, installs both agent skills and the smd MCP server (.claude-plugin/marketplace.json and plugin.json; the server is declared in the plugin, so there is no root .mcp.json). The plugin's version is the release's: bump-version.mjs sets it and check-versions.mjs fails a tag whose plugin.json doesn't match. Setup: INSTALL.md.

• MCP Registry entry: server.json describes the MCP server as the npm package (npx styled-markdown mcp), and npm/package.json has the mcpName (io.github.bislink360/styled-markdown) the registry checks. Its versions follow the release like the plugin's. Publishing is a maintainer step after the npm release: docs/PUBLISHING.md.

• Spec-driven workflow kit: three new templates, spec (requirements with IDs, acceptance criteria, open questions, rules for implementers), plan (approach, decisions, risks, phases; related: the spec) and tasks (the agent's work queue by phase, with requirement, priority, owner and due date, and how to check tasks off), for one folder per feature. smd init x.smd --template spec and the writer skill have 16 templates now. docs/SPEC-DRIVEN.md walks through spec, plan and tasks with an agent: smd tasks as the work queue, smd validate as the gate, and check_task (with smd mcp --allow-write) or a line edit to tick tasks off.

• Reading .smd on GitHub: docs/GITHUB.md compares the ways to make documents readable on github.com: Styled Markdown syntax in .md files (what GitHub renders, and which smd commands read .md files), .md copies generated in CI with smd export --to md (a complete workflow that commits the copies on main and checks them on pull requests), and a pull request comment with the changed sections in the agent view (smd diff --since). It also says what *.smd linguist-language=Markdown in .gitattributes does: highlighting and language statistics, not rendering.

• Compatibility policy: docs/COMPATIBILITY.md declares spec v2 stable (a breaking change needs a spec v3 RFC), versions the spec apart from the tools (spec 2, tools 2.5.0), says what patch, minor and major releases may change, and sets the deprecation policy (deprecate in a minor, remove in the next major at the earliest) and the cadence (a minor roughly monthly, patches as needed). SPEC.md links it from its header.

• Homepage and hosted playground: a Pages workflow publishes a homepage (site/index.smd, built with smd build) at https://bislink360.github.io/styled-markdown/ and the web playground at /playground/, from main.

• Community files: issue forms for bug reports and feature requests (with links to Discussions, the docs and private vulnerability reporting), a pull request template for outside contributors, CODE_OF_CONDUCT.md (Contributor Covenant 2.1), SECURITY.md (the latest minor is supported; report through GitHub's private vulnerability reporting), and a "Good first issues" section in CONTRIBUTING.md.

• Adoption report: node extension/scripts/adoption.mjs [--json] prints stars, forks, issues and pull requests from outside contributors, release asset downloads, npm, VS Code Marketplace, Open VSX and PyPI downloads, and a count of public smd: 2 documents; a registry without the package shows "not listed". The Adoption workflow writes it to the job summary every Monday.

Changed

• The MCP server lists four tools instead of six, and they cost ≈500 tokens instead of ≈1,320. Every agent session pays for the tool list, so read replaces outline, section and agent in it, and the descriptions are shorter. The old tools still work when a client calls them, and smd mcp --legacy-tools lists them again; they stay until 3.0. The server's instructions point agents at read.

• Reader skill costs ≈480 tokens instead of ≈2,300. SKILL.md now starts with smd read FILE, one call. It tells agents to read files under ≈1,500 tokens (≈6 KB) directly, since the tools don't pay off there, and keeps the rules for <agent-instructions>, decisions and open questions. Its description is shorter too, but keeps the words that make it trigger (spec, PRD, ADR, runbook, "the doc").

• Agent rules cost ≈280 tokens instead of ≈820. The Cursor rule, the Copilot instructions and the AGENTS.md section from smd skills install --target are now a short version that leads with smd read. This matters because AGENTS.md is in context in every session.

• Writer syntax reference split by topic. references/syntax.md is now a short index (≈370 tokens) of eight files under references/syntax/: basics, callouts, project blocks, developer blocks, layout, figures and notes, inline, and spec v2. Agents load only the topic they need (≈200–950 tokens) instead of the whole ≈4,550-token file. No rule was dropped.

• Writer skill writes meaning, not styling. SKILL.md (≈1,650 tokens, was ≈2,090) tells agents to spend tokens on decisions, risks, tasks, :::agent and {agent=skip}, and to leave colors and layout to people, since output tokens cost about 5× input. It also says to load one syntax topic at a time and to let smd validate --fix catch the rest.

• README rewritten around agent users: a one-sentence pitch, then the install commands (Claude Code plugin, smd init --agent, VS Code, npm), then what the tools do for agents. The token claim "typically cutting 37–85%" is replaced with the measured ranges of TOKENS.md: the full agent view is 5–37% smaller than the file on the examples (median ≈17%), --brief 14–43%, the outline plus one section about 80% smaller on 6k–8k-token documents, and small documents (under ≈1,500 tokens) are cheaper to read directly. The long feature lists moved to an "At a glance" section in FEATURES.md, the per-integration install sections to INSTALL.md (which gains agent setup, the npm library, markdown-it and remark/rehype plugins and the single-file CLI), and the repository layout to CONTRIBUTING.md.

• Install docs point VS Code users at the Marketplace listing (code --install-extension bislink360.styled-markdown); the .vsix stays the way in for Cursor, VSCodium and Windsurf until the Open VSX listing is live.

• Names lead with "Styled Markdown" for search: the VS Code extension's description ("Styled Markdown: Markdown for humans and AI agents. …"), the GitHub Action's name (Styled Markdown validate (smd); still used as bislink360/styled-markdown/validate@…), and the titles of the install guide ("Installing Styled Markdown"), the feature guide ("Styled Markdown feature guide") and the examples README ("Styled Markdown examples"). No ids, package names or paths changed.

Deprecated

• The MCP tools outline, section and agent: use read (with mode: "outline", sections, or mode: "full"). They keep working, unlisted, until 3.0.