In short:
ak-previewdoes two things: it opens an existing Markdown file or folder in a browser reader, or it builds a new explainer, diagram, slide deck, diff review page, plan-versus-code page or project recap. The output is a Markdown file or a self-contained HTML file, saved in the visuals folder next to the plan. For publication-quality SVG/PNG diagrams, it hands off toak-tech-graph.
Disclosure: I maintain AgentKit and have an affiliate relationship with it: the AgentKit link in this post is an affiliate link; buying through it gets you 30% off.
Summary
Use it when you need to see rather than read: reading a long document, understanding a code path, getting an architecture diagram to share, reviewing a branch before merging, presenting a plan as slides, or catching up on a project after some time away. If you only want a quick look in the terminal, use --ascii.
flowchart LR
A["Existing .md file"] --> P["ak-preview"]
B["Topic, diff, plan, time range"] --> P
P --> C["Markdown reader in the browser"]
P --> D[".md or .html file in visuals/"]
D --> E["ak-tech-graph when you need SVG/PNG to publish"]
D --> F["Stop, you look and decide"]Four concepts to know:
| Concept | Question | Example |
|---|---|---|
| View or create | Do you want to open something that exists, or build a new picture? | /ak-preview docs/guide.md opens the reader; /ak-preview --explain the sign-in flow writes a new file |
| Markdown or HTML | How is the result viewed? | Without --html: a .md file viewed through a server; with --html: one .html file that opens directly |
| Where files go | Where does the output file live? | With an active plan it goes into that plan's visuals/ folder, otherwise into plans/visuals/ |
| HTML build path | Who handles the layout and look of the HTML page? | By default the skill writes HTML from a template; with --ak-render it writes a .page.yaml for AK Render to compile |
If the file name already exists, the old file in the visuals folder is overwritten without asking.
Sample prompt for reviewing a branch before merging:
/ak-preview --html --diff <branch name or PR number>| Flag | What it is for | Since ak |
|---|---|---|
--html | Outputs one self-contained HTML file instead of Markdown | 1.0.0 |
--explain | Visually explains a concept or a code path | 1.0.0 |
--slides | Builds a presentation deck | 1.0.0 |
--diagram | One focused diagram, in ASCII and Mermaid | 1.0.0 |
--ascii | Character-only diagram, viewed in the terminal | 1.0.0 |
--diff | A visual review page for a change | 1.0.0 |
--plan-review | Puts the plan next to the real code to check it | 1.0.0 |
--recap | A snapshot of the project's context over a time range | 1.0.0 |
--ak-render | Builds the HTML page with AK Render | 3.0.0-beta.5 |
--no-antv, --no-diagram-design, --no-editorial-visuals | Turns off the illustration layers in the HTML page | 2.13.0 |
--stop | Stops the running viewer server | 1.0.0 |
Below is the detailed version: the run flow, 6 situations with prompts, each flag explained (when to use it, when you do not need it, what you get, which flags it combines with), the change history by ak release, and common pitfalls. The detailed version and the interactive page are for subscribers. Your agent can also search them through the portal's MCP.
Opens when your account has subscriber access
This guide is for subscribers
Once your account has access, the full piece, the interactive visual and the agent call all open.
- Sign in or create a modernEngineer accountReading access belongs to your account email.
- Choose a plan on the pricing page1, 3 or 12 months, paid by VietQR bank transfer. Access opens about a minute after the money arrives.
- Or redeem a Facebook subscriber codePeople supporting the page on Facebook get an activation code by message each month.
Already a subscriber? Sign in to read.
Use this piece in your agent
Get an API keyCopy the text below and paste it into Claude Code, Codex or whichever agent you use. The agent reads the piece and checks it against the repo you have open.
Read "ak-preview: view Markdown and build explainers, diagrams, slides" on modernEngineer and apply it to this repo.
1. Call the content_get tool of the modernengineer MCP server with locale "en", slug "ak-preview". If the modernengineer MCP server is not connected, stop and walk me through connecting it from https://modernengineer.dev/en/mcp.
2. Summarize the main steps of the piece and point out which apply to this repo.
3. Propose concrete changes and ask me before editing any file.Connect MCP in Claude Code (once)
claude mcp add --transport http modernengineer \
https://api.modernengineer.dev/mcp \
--header "Authorization: Bearer <API key>"Reading the full piece over MCP needs an API key from a subscriber account or one that bought this guide. Without access, the agent only gets the opening.
- Version
- v1.0.0
- Updated
- 22/10/2026
- Licence
- All rights reserved
- Slug
- ak-preview
