docslice
docslice gives terminals and LLM agents section-level access to any deployed MyST site, without the site changing anything. It reads the JSON endpoints every MyST site already publishes, so you can pull out one section as markdown instead of fetching and parsing whole pages.
The goal is progressive disclosure for agents. A docs site is already a structured knowledge base, and this tool lets an agent survey it, then read just the sections it needs, keeping context small. That matters most for smaller and open-weights models, which can’t absorb whole sites. And because the site is queried directly, nobody maintains a separate set of agent-facing skill files: the docs stay the single source of truth.
Setup¶
Install the docslice command from npm:
npm install -g docsliceOr run it without installing, as npx docslice <command>.
Working from a checkout of this repo instead is covered in Developing docslice.
Using it¶
Paste any section link copied from your browser, and get that section back as markdown:
docslice get 'https://mystmd.org/guide/quickstart#install-the-myst-markdown-cli'warning: some content didn't convert to markdown (Unexpected tabSet node child is not tabItem: undefined)
warning: some content didn't convert to markdown (Unexpected tabSet node child is not tabItem: undefined)
warning: some content didn't convert to markdown (Unexpected tabSet node child is not tabItem: undefined)
## Install the {abbr}`MyST (Markedly Structured Text)` Markdown {abbr}`CLI (Command Line Interface)`
🛠 Install {abbr}`MyST (Markedly Structured Text)` using your preferred packaging ecosystem. (See [Install the MyST Markdown Command Line Interface](/installing) for more details).
:::{tip} Not sure which to pick?
:class: dropdown
The easiest way to install {abbr}`MyST (Markedly Structured Text)` is with the `mamba` package manager. `mamba` is a cross-platform language-agnostic package manager that is useful for users across many data science languages like Python, R, Julia, and JavaScript.
:::
```{embed}
```
🛠 Then, check that {abbr}`MyST (Markedly Structured Text)` has successfully been installed:
```shell
$ myst -v
v1.3.4
```
Leave off the #anchor to print the whole page.
You can also give the site root plus any MyST label, and docslice finds it wherever it lives on the site:
docslice get 'https://mystmd.org/guide#sunset-figure':::{figure} https://github.com/rowanc1/pics/blob/main/sunset.png
:name: sunset-figure
Here’s a nice sunset with a caption!
:::
See a site’s pages, or one page’s headings and their anchors:
docslice outline https://mystmd.org/guide | headhttps://mystmd.org/guide/ MyST Markdown Tools
https://mystmd.org/guide/installing Install the MyST Markdown Command Line Interface
https://mystmd.org/guide/quickstart Get Started
https://mystmd.org/guide/quickstart-myst-documents Scientific Articles
https://mystmd.org/guide/quickstart-executable-documents Executable Documents
https://mystmd.org/guide/quickstart-static-exports Export Static Documents
https://mystmd.org/guide/quickstart-myst-markdown Working with MyST Markdown
https://mystmd.org/guide/quickstart-jupyter-lab-myst MyST with Jupyter Interfaces
https://mystmd.org/guide/configuration Configuration and content frontmatter
https://mystmd.org/guide/frontmatter Content frontmatter options
docslice outline https://mystmd.org/guide /figures Simple images #simple-images
Image directive #image-directive
Figure directive #figure-directive
Subfigures #subfigures
Control sub-figure layout with a grid #control-sub-figure-layout-with-a-grid
Supported Image Formats #supported-image-formats
Image Transformers #image-transformers
Multiple Images #figures-multiple-images
Videos #videos
Use an image in place of a video for static exports #use-an-image-in-place-of-a-video-for-static-exports
YouTube Videos #youtube-videos
Provide Light and Dark Mode images #provide-light-and-dark-mode-images
List everything of one kind across a site, like every figure:
docslice list figures https://mystmd.org/guide | headfrontmatter-before https://mystmd.org/guide/quickstart#frontmatter-before
frontmatter-site-title https://mystmd.org/guide/quickstart#frontmatter-site-title
frontmatter-before-pdf https://mystmd.org/guide/quickstart-myst-documents#frontmatter-before-pdf
frontmatter-after https://mystmd.org/guide/quickstart-myst-documents#frontmatter-after
references https://mystmd.org/guide/quickstart-myst-documents#references
figure-hover https://mystmd.org/guide/quickstart-myst-documents#figure-hover
export-docx https://mystmd.org/guide/quickstart-static-exports#export-docx
export-pdf https://mystmd.org/guide/quickstart-static-exports#export-pdf
jupyterlab-myst https://mystmd.org/guide/quickstart-jupyter-lab-myst#jupyterlab-myst
fig:eval-array https://mystmd.org/guide/quickstart-jupyter-lab-myst#fig-eval-array
Search every page of a site for a phrase:
docslice search https://mystmd.org/guide "kernelspec"https://mystmd.org/guide/notebooks-with-markdown#kernel-specification Defining a kernel specification ( kernelspec ) informs the Jupyter server of the name of the kernel that
https://mystmd.org/guide/execute-notebooks#skip-entire-notebooks ting the execute.skip frontmatter option to true , e.g. --- kernelspec: name: python3 display_name: Python 3 execute: skip: true -
https://mystmd.org/guide/notebooks-with-markdown#execute-config skip Skip execution of this notebook, even though it has a kernelspec. depends_on_env Define the environment variables upon which
https://mystmd.org/guide/notebook-configuration#markdown-notebooks tebook, you would add the following to the frontmatter: --- kernelspec: name: python3 display_name: Python 3 execute: skip: true -
https://mystmd.org/guide/notebooks-with-markdown#use-a-different-kernel l, e.g. ijavascript . Retrieve the kernel name with jupyter kernelspec list . In the default installation, the kernel name is java
https://mystmd.org/guide/configuration#in-a-jupyter-notebook : text_representation: extension: .md format_name: markdown kernelspec: display_name: Python 3 (ipykernel) language: python name:
https://mystmd.org/guide/frontmatter#all-available-frontmatter-fields for Jupyter execution (see In-Page Execution ) project only kernelspec configuration for the kernel (see Kernel specification ) pa
The first search on a site fetches every page, so it’s slower; later searches reuse the cache.
Add --format json to get for the raw mdast instead of markdown, or --depth 0 to trim a section down to just its own content, without subsections.
A warning: line on stderr means docslice couldn’t convert part of the content to markdown; AST renderer gaps tracks these cases.
Fetches are cached for a day under ~/.cache/docslice; docslice cache shows what’s stored, and docslice cache clear forces fresh fetches.
As a library¶
The CLI is a thin wrapper over a small library. From a checkout of this repo, save this as example.mts and run it with npx tsx example.mts:
import { subsetByAnchor } from './src/mdast.js';
import { renderMd } from './src/render.js';
const page = await (await fetch('https://mystmd.org/guide/quickstart.json')).json();
const section = subsetByAnchor(page.mdast, 'install-the-myst-markdown-cli');
console.log(renderMd(section).markdown);Roadmap¶
This is a hackweek project. Still to come:
An MCP server exposing the same operations
For a skill teaching LLM agents to use the CLI, see Agent skill.
Contributing¶
Developing docslice has setup and the conventions for working on the code. The other pages under Development record the why behind them: design decisions, the survey of real MyST sites, and known renderer gaps.