langchain-ai/docs
1
0
Fork 0
mirror of https://github.com/langchain-ai/docs.git synced 2026-07-22 20:35:34 -04:00
Code Issues 490 Packages Projects Releases Wiki Activity

[PR #623] [CLOSED] feat: docs snippets #867

New Issue
Closed
opened 2026-02-17 17:21:16 -05:00 by yindo · 0 comments
yindo commented 2026-02-17 17:21:16 -05:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/langchain-ai/docs/pull/623
Author: @hntrl
Created: 9/22/2025
Status: ❌ Closed

Base: main ← Head: hunter/snippets-command

📝 Commits (1)

📊 Changes

26 files changed (+3043 additions, -788 deletions)

View changed files

📝 Makefile (+7 -1)
📝 README.md (+26 -1)
➖ package-lock.json (+0 -6)
📝 pipeline/cli.py (+79 -0)
➕ pipeline/commands/snippets.py (+50 -0)
➕ pipeline/constants.py (+51 -0)
➕ pipeline/core/snippets.py (+422 -0)
📝 pipeline/preprocessors/handle_auto_links.py (+4 -32)
📝 pipeline/preprocessors/markdown_preprocessor.py (+15 -9)
📝 pipeline/tools/highlights.py (+3 -9)
📝 pyproject.toml (+6 -0)
➕ snippets/python/.gitignore (+6 -0)
➕ snippets/python/Makefile (+8 -0)
➕ snippets/python/pyproject.toml (+28 -0)
➕ snippets/python/uv.lock (+8 -0)
➕ snippets/typescript/.gitignore (+7 -0)
➕ snippets/typescript/Makefile (+6 -0)
➕ snippets/typescript/eslint.config.mts (+19 -0)
➕ snippets/typescript/package.json (+21 -0)
➕ snippets/typescript/pnpm-lock.yaml (+1407 -0)

...and 6 more files

📄 Description

This PR introduces a docs snippets command that statically extracts and lints all code snippets contained within docs to a snippets/ folder.

Motivation

New Commands

  • docs snippets will clean, export, and lint all code snippet files
  • docs snippets clean will clean all non-boilerplate files from the snippets directories
  • docs snippets export will only extract code snippets from docs files
  • docs snippets lint will only lint code snippet files already exported to the snippets folder

New code block directives

export

To make this change opt-in, code blocks will only be exported into the snippets folder if it has an export attribute. For instance:

<!-- this will be exported -->
\`\`\`python export
2 + 2
\`\`\`
<!-- this will not be exported -->
\`\`\`python
secret_to_life = 42
\`\`\`

ignore

This directive is only for rendering snippets in the final docs build, and is meant to be used in conjunction with merge-before to give additional scope to the snippet

<!-- this codeblock will not end up in a final build artifact -->
\`\`\`python ignore
print("you wont see me")
\`\`\`

merge-before

You can use this to merge code blocks together into one consistent snippet -- this is helpful for examples that span across multiple code snippets, but still should be treated as one consistent example when we go to export the snippet and lint.

\`\`\`python
foo = "bar"
\`\`\`
\`\`\`python merge-before
print(foo)
\`\`\`

When used with the ignore directive, you can pin additional scopes to the snippet without it being rendered in the final docs build. For instance:

\`\`\`python ignore
from langchain.agents import create_agent
\`\`\`
\`\`\`python merge-before
agent = create_agent(...)
\`\`\`

Structure change: snippets/

This PR adds a top level snippets/ directory that contains each language's boilerplate code for linting + formatting. When docs snippets is run, all code snippets will be exported into each languages directory to be linted and formatted.

Each language directory contains a Makefile that has a lint command that kicks off a linting command for all exported snippets. For python we run the same lint commands as we do in the root of the directory (with some special docs-only rules applied in pyproject.toml, and in JS we run the lint pnpm script which triggers an eslint run.

Each snippet file that gets exported is intentionally not tracked -- we should only really need these snippet files for CI reasons (for now)

Test cases

(might be good as unit tests, but these are just one off checks I've done for now)

  • Verify that existing code block rendering is not affected
  • Verify that code blocks with the merge-before directive are collapsed into one code snippet
  • Verify that code blocks with the ignore directive are omitted from the final build
  • Verify that code blocks are only exported to snippets/ if it contains the export directive
  • Verify that lints are applied correctly across python and typescript

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/langchain-ai/docs/pull/623 **Author:** [@hntrl](https://github.com/hntrl) **Created:** 9/22/2025 **Status:** ❌ Closed **Base:** `main` ← **Head:** `hunter/snippets-command` --- ### 📝 Commits (1) - [`c40daf4`](https://github.com/langchain-ai/docs/commit/c40daf4ebdedcd234400eec1e4720071908aeae2) feat: `docs snippets` ### 📊 Changes **26 files changed** (+3043 additions, -788 deletions) <details> <summary>View changed files</summary> 📝 `Makefile` (+7 -1) 📝 `README.md` (+26 -1) ➖ `package-lock.json` (+0 -6) 📝 `pipeline/cli.py` (+79 -0) ➕ `pipeline/commands/snippets.py` (+50 -0) ➕ `pipeline/constants.py` (+51 -0) ➕ `pipeline/core/snippets.py` (+422 -0) 📝 `pipeline/preprocessors/handle_auto_links.py` (+4 -32) 📝 `pipeline/preprocessors/markdown_preprocessor.py` (+15 -9) 📝 `pipeline/tools/highlights.py` (+3 -9) 📝 `pyproject.toml` (+6 -0) ➕ `snippets/python/.gitignore` (+6 -0) ➕ `snippets/python/Makefile` (+8 -0) ➕ `snippets/python/pyproject.toml` (+28 -0) ➕ `snippets/python/uv.lock` (+8 -0) ➕ `snippets/typescript/.gitignore` (+7 -0) ➕ `snippets/typescript/Makefile` (+6 -0) ➕ `snippets/typescript/eslint.config.mts` (+19 -0) ➕ `snippets/typescript/package.json` (+21 -0) ➕ `snippets/typescript/pnpm-lock.yaml` (+1407 -0) _...and 6 more files_ </details> ### 📄 Description This PR introduces a `docs snippets` command that statically extracts and lints all code snippets contained within docs to a `snippets/` folder. ### Motivation * #530 * Allows us to bring language-independent tooling for linting + formatting * Gives us a hatch to do additional static analysis later down the line ## New Commands - `docs snippets` will clean, export, and lint all code snippet files - `docs snippets clean` will clean all non-boilerplate files from the snippets directories - `docs snippets export` will only extract code snippets from docs files - `docs snippets lint` will only lint code snippet files already exported to the snippets folder ## New code block directives ### `export` To make this change opt-in, code blocks will only be exported into the snippets folder if it has an `export` attribute. For instance: ```md <!-- this will be exported --> \`\`\`python export 2 + 2 \`\`\` <!-- this will not be exported --> \`\`\`python secret_to_life = 42 \`\`\` ``` ### `ignore` This directive is only for rendering snippets in the final docs build, and is meant to be used in conjunction with `merge-before` to give additional scope to the snippet ```md <!-- this codeblock will not end up in a final build artifact --> \`\`\`python ignore print("you wont see me") \`\`\` ``` ### `merge-before` You can use this to merge code blocks together into one consistent snippet -- this is helpful for examples that span across multiple code snippets, but still should be treated as one consistent example when we go to export the snippet and lint. ```md \`\`\`python foo = "bar" \`\`\` \`\`\`python merge-before print(foo) \`\`\` ``` When used with the `ignore` directive, you can pin additional scopes to the snippet without it being rendered in the final docs build. For instance: ```md \`\`\`python ignore from langchain.agents import create_agent \`\`\` \`\`\`python merge-before agent = create_agent(...) \`\`\` ``` ## Structure change: `snippets/` This PR adds a top level `snippets/` directory that contains each language's boilerplate code for linting + formatting. When `docs snippets` is run, all code snippets will be exported into each languages directory to be linted and formatted. Each language directory contains a Makefile that has a `lint` command that kicks off a linting command for all exported snippets. For python we run the same lint commands as we do in the root of the directory (with some special docs-only rules applied in `pyproject.toml`, and in JS we run the `lint` pnpm script which triggers an eslint run. Each snippet file that gets exported is intentionally not tracked -- we should only really need these snippet files for CI reasons (for now) ## Test cases (might be good as unit tests, but these are just one off checks I've done for now) - [ ] Verify that existing code block rendering is not affected - [x] Verify that code blocks with the `merge-before` directive are collapsed into one code snippet - [x] Verify that code blocks with the `ignore` directive are omitted from the final build - [x] Verify that code blocks are only exported to `snippets/` if it contains the `export` directive - [x] Verify that lints are applied correctly across python and typescript --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
yindo added the pull-request label 2026-02-17 17:21:16 -05:00
yindo closed this issue 2026-02-17 17:21:16 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
deepagents
docs-infra
external
external
help wanted
integration
internal
internal
javascript
js/ts
langchain
langgraph
langsmith
needs-title
pull-request
Mirrored from GitHub Pull Request
 python
reference
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langchain-ai/docs#867
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?