General contributing maintenance

.github/copilot-instructions.md

@@ -2,7 +2,7 @@
 
 This repository encompasses the comprehensive documentation for LangChain's products and services, all hosted on the Mintlify platform. The documentation is divided into sections for each product. This is a shared set of guidelines to ensure consistency and quality across all content.
 
-## Folder Structure
+## Folder structure
 
 All documentation lives in the `src/` folder, with the following structure:
 
@@ -14,14 +14,15 @@ All documentation lives in the `src/` folder, with the following structure:
     - `/reference`: Links out to reference docs for both LangChain and LangGraph
     - `/contributing`: Guidelines on contributing to the docs, codebase, and submit integrations
     - `/images`: Shared images used across OSS docs
+    - `/concepts`: Shared concepts used across OSS docs
     - The root contains product/language agnostic meta-info such as our versioning & release policy and the releases page.
 - `/langsmith`: Documentation for LangSmith, including quickstarts, observability, evaluation, prompt engineering, self hosting, and administration.
 - `/langgraph-platform`: Documentation for the LangGraph Platform, including quickstarts, features, guides on building & deploying using the platform, management & administration, and reference docs.
 - `/labs`: Home to LangChain's experimental AI products, including deep agents, open SWE, and Open Agent Platform
 - `/images`: Shared images used across all docs
 - `/snippets`: Shared code snippets used across all docs
 
-## Libraries and Frameworks
+## Libraries and frameworks
 
 Documentation is written for Mintlify's MDX syntax and uses Mintlify components. For questions, refer to the Mintlify docs (either via MCP, if available), or at the [Mintlify documentation](https://docs.mintlify.com/docs/introduction).
 
@@ -62,10 +63,19 @@ If the trailing `/index` (no extension included) is omitted, the Mintlify parser
 
 ## Frontmatter requirements for pages
 
-- title: Clear, descriptive page title
-- description: Concise summary for SEO/navigation
+- title: Clear, descriptive, concise page title
 
-## Writing standards
+## Custom code language fences
+
+We have implemented custom code language fences for Python and Javascript. They are used to tag content that is specific to that language. Use either `:::python` or `:::js` to tag content that is specific to that language. Both are closed with the `:::` fence.
+
+If any code fences like this exist on the code page, then two outputs (one for each language) will be created. For example, if this syntax is on the page in `/concepts/foo.mdx`, two pages will be created at `/python/concepts/foo.mdx` and `/javascript/concepts/foo.mdx`.
+
+For implementation details, see `pipeline/preprocessors/markdown_preprocessor.py`.
+
+## Style guide
+
+In general, follow the [Google Developer Documentation Style Guide](https://developers.google.com/style). You can also access this style guide through the [Vale-compatible implementation](https://github.com/errata-ai/Google).
 
 - Second-person voice ("you")
 - Prerequisites at start of procedural content
@@ -74,9 +84,10 @@ If the trailing `/index` (no extension included) is omitted, the Mintlify parser
 - Include both basic and advanced use cases
 - Language tags on all code blocks
 - Alt text on all images
-- Relative paths for internal links
+- Root relative paths for internal links
 - Correct spelling
 - Correct grammar
+- Sentence-case for headings
 
 ## Do not
 

README.md

@@ -1,4 +1,4 @@
-# Documentation Build Pipeline
+# Documentation build pipeline
 
 This repository contains the documentation build pipeline for LangChain projects.
 
@@ -8,7 +8,7 @@ The pipeline is structured with source files in `/src` and build artifacts in `/
 
 Documentation changes follow a PR workflow where all tests must pass before merging. Publishing is handled by the [publish workflow](https://github.com/langchain-ai/docs/actions/workflows/publish.yml) (requires authorization), and [preview branches](https://github.com/langchain-ai/docs/actions/workflows/create-preview-branch.yml) are available for testing changes.
 
-## Directory Structure
+## Directory structure
 
 ```text
 src/                  # Source documentation files (edit these)
@@ -60,16 +60,16 @@ Makefile              # Build automation
    - `docs migrate <path>` - Convert MkDocs markdown files to Mintlify format
    - `docs migrate-docusaurus <path>` - Convert Docusaurus markdown files to Mintlify format
 
-### Important Rules
+### Important rules
 
 - **Only edit files in `src/`** - The `build/` directory is automatically generated
 - **Use Mintlify syntax** - See [Mintlify documentation](https://mintlify.com/docs) for formatting guidelines
 - **Test your changes** - Use `docs dev` to preview changes locally with hot reload (on save)
 - **Use safe Mintlify commands** - Use `make mint-broken-links` instead of `mint broken-links` to check final built documentation
 
-### Available Commands
+### Available commands
 
-#### Make Commands
+#### Make commands
 
 - `make dev` - Start development mode with file watching and live rebuild
 - `make build` - Build documentation to `./build` directory
@@ -113,20 +113,21 @@ These can be used directly using the `Makefile` or via the `docs` CLI tool:
 - **`docs build`** - Build documentation files
   - `--watch` - Watch for file changes after building
 
-### File Formats
+### File formats
 
 - **Markdown files** (`.md`, `.mdx`) - Standard documentation content
-- **Jupyter notebooks** (`.ipynb`) - Converted to markdown during build
+- **Jupyter notebooks** (`.ipynb`) - Converted to markdown during build, though these are not recommended for new content.
 - **Assets** - Images and other files are copied to the build directory
 
-### Documentation Syntax
+### Documentation syntax
 
 This project uses [Mintlify](https://mintlify.com/docs) for documentation generation. Key features:
 
 - **Frontmatter** - YAML metadata at the top of files
 - **Components** - Special Mintlify components for enhanced formatting
 - **Code blocks** - Syntax highlighting and copy functionality
 - **Navigation** - Automatic sidebar generation from file structure
+- **Code language fences** - Custom code language fences for Python and Javascript (`:::python` and `:::js`). Both are closed with the `:::` fence. These are used to tag content that is specific to that language and will generate two outputs: one for each language.
 
 Refer to the [Mintlify documentation](https://mintlify.com/docs) for detailed syntax and component usage.
 
@@ -138,7 +139,7 @@ Run the test suite to ensure your changes don't break existing functionality:
 make test
 ```
 
-### Code Quality
+### Code quality
 
 Before submitting changes, ensure your code passes formatting and linting checks:
 
@@ -155,7 +156,7 @@ make lint_md_fix
 
 **Note**: All pull requests are automatically checked by CI/CD. The same linting and formatting standards will be enforced, and PRs cannot be merged if these checks fail.
 
-## Development Workflow
+## Development workflow
 
 1. **Start development mode:**
 

src/langgraph-platform/autogen-integration.mdx

@@ -6,7 +6,7 @@ This guide shows how to integrate AutoGen agents with LangGraph to leverage feat
 
 Integrating AutoGen with LangGraph provides several benefits:
 
-* Enhanced features: Add [persistence](/oss/langgraph/persistence), [streaming](/langgraph-platform/streaming), [short and long-term memory](/oss/memory) and more to your AutoGen agents.
+* Enhanced features: Add [persistence](/oss/langgraph/persistence), [streaming](/langgraph-platform/streaming), [short and long-term memory](/oss/concepts/memory) and more to your AutoGen agents.
 * Multi-agent systems: Build [multi-agent systems](/oss/langchain/multi-agent) where individual agents are built with different frameworks.
 * Production deployment: Deploy your integrated solution to [LangGraph Platform](/langgraph-platform/index) for scalable production use.
 

src/langgraph-platform/langgraph-studio.mdx

@@ -23,7 +23,7 @@ Key features of LangGraph Studio:
 * [Manage threads](/langgraph-platform/threads-studio)
 * [Iterate on prompts](/langgraph-platform/iterate-graph-studio)
 * [Run experiments over a dataset](/langgraph-platform/run-evals-studio)
-* Manage [long term memory](/oss/memory)
+* Manage [long term memory](/oss/concepts/memory)
 * Debug agent state via [time travel](/oss/langgraph/use-time-travel)
 
 LangGraph Studio works for graphs that are deployed on [LangGraph Platform](/langgraph-platform/deployment-quickstart) or for graphs that are running locally via the [LangGraph Server](/langgraph-platform/local-server).

src/langgraph-platform/quick-start-studio.mdx

@@ -14,7 +14,7 @@ LangGraph Studio is accessed from the LangSmith UI, within the **LangGraph Platf
 
 For applications that are [deployed](/langgraph-platform/deployment-quickstart) on LangGraph Platform, you can access Studio as part of that deployment. To do so, navigate to the deployment in LangGraph Platform within the LangSmith UI and click the **LangGraph Studio** button.
 
-This will load the Studio UI connected to your live deployment, allowing you to create, read, and update the [threads](/oss/langgraph/persistence#threads), [assistants](/langgraph-platform/assistants), and [memory](/oss/memory) in that deployment.
+This will load the Studio UI connected to your live deployment, allowing you to create, read, and update the [threads](/oss/langgraph/persistence#threads), [assistants](/langgraph-platform/assistants), and [memory](/oss/concepts/memory) in that deployment.
 
 ## Local development server
 

src/langgraph-platform/streaming.mdx

@@ -436,7 +436,7 @@ Use this to stream the **full state** of the graph after each step.
 
 ## Subgraphs
 
-To include outputs from [subgraphs](/oss/subgraphs) in the streamed outputs, you can set `subgraphs=True` in the `.stream()` method of the parent graph. This will stream outputs from both the parent graph and any subgraphs.
+To include outputs from [subgraphs](/oss/concepts/subgraphs) in the streamed outputs, you can set `subgraphs=True` in the `.stream()` method of the parent graph. This will stream outputs from both the parent graph and any subgraphs.
 
 ```python {highlight={5}}
 for chunk in client.runs.stream(

src/oss/context.mdx → src/oss/concepts/context.mdx

@@ -142,7 +142,7 @@ await graph.invoke(
 <a id="state"></a>
 ## Dynamic runtime context
 
-**Dynamic runtime context** represents mutable data that can evolve during a single run and is managed through the LangGraph state object. This includes conversation history, intermediate results, and values derived from tools or LLM outputs. In LangGraph, the state object acts as [short-term memory](/oss/memory) during a run.
+**Dynamic runtime context** represents mutable data that can evolve during a single run and is managed through the LangGraph state object. This includes conversation history, intermediate results, and values derived from tools or LLM outputs. In LangGraph, the state object acts as [short-term memory](/oss/concepts/memory) during a run.
 
 <Tabs>
     <Tab title="In an agent">
@@ -295,11 +295,11 @@ Please see the [memory guide](/oss/langgraph/add-memory) for more details on how
 <a id="store"></a>
 ## Dynamic cross-conversation context
 
-**Dynamic cross-conversation context** represents persistent, mutable data that spans across multiple conversations or sessions and is managed through the LangGraph store. This includes user profiles, preferences, and historical interactions. The LangGraph store acts as [long-term memory](/oss/memory#long-term-memory) across multiple runs. This can be used to read or update persistent facts (e.g., user profiles, preferences, prior interactions).
+**Dynamic cross-conversation context** represents persistent, mutable data that spans across multiple conversations or sessions and is managed through the LangGraph store. This includes user profiles, preferences, and historical interactions. The LangGraph store acts as [long-term memory](/oss/concepts/memory#long-term-memory) across multiple runs. This can be used to read or update persistent facts (e.g., user profiles, preferences, prior interactions).
 
 ## See also
 
-- [Memory conceptual overview](/oss/memory)
+- [Memory conceptual overview](/oss/concepts/memory)
 - [Short-term memory in LangChain](/oss/langchain/short-term-memory)
 - [Long-term memory in LangChain](/oss/langchain/long-term-memory)
 - [Memory in LangGraph](/oss/langgraph/add-memory)

src/oss/contributing/documentation.mdx

@@ -183,9 +183,9 @@ Conceptual guide cover core concepts abstractly, providing deep understanding.
 </AccordionGroup>
 
 **Example pages**
-- [Memory](/oss/memory)
-- [Context](/oss/context)
-- [Subgraphs](/oss/subgraphs)
+- [Memory](/oss/concepts/memory)
+- [Context](/oss/concepts/context)
+- [Subgraphs](/oss/concepts/subgraphs)
 
 ### References
 

src/oss/langchain/agents.mdx

@@ -593,7 +593,7 @@ const CustomAgentState = createAgent({
 :::
 
 <Tip>
-To learn more about memory, see [Memory](/oss/memory). For information on implementing long-term memory that persists across sessions, see [Long-term memory](/oss/langchain/long-term-memory).
+To learn more about memory, see [Memory](/oss/concepts/memory). For information on implementing long-term memory that persists across sessions, see [Long-term memory](/oss/langchain/long-term-memory).
 </Tip>
 
 ### Pre-model hook

src/oss/langgraph/add-memory.mdx

@@ -6,7 +6,7 @@ import AlphaCallout from '/snippets/alpha-lg-callout.mdx';
 
 <AlphaCallout />
 
-AI applications need [memory](/oss/memory) to share context across multiple interactions. In LangGraph, you can add two types of memory:
+AI applications need [memory](/oss/concepts/memory) to share context across multiple interactions. In LangGraph, you can add two types of memory:
 
 * [Add short-term memory](#add-short-term-memory) as a part of your agent's [state](/oss/langgraph/graph-api#state) to enable multi-turn conversations.
 * [Add long-term memory](#add-long-term-memory) to store user-specific or application-level data across sessions.
@@ -437,7 +437,7 @@ const graph = builder.compile({ checkpointer });
 
 ### Use in subgraphs
 
-If your graph contains [subgraphs](/oss/subgraphs), you only need to provide the checkpointer when compiling the parent graph. LangGraph will automatically propagate the checkpointer to the child subgraphs.
+If your graph contains [subgraphs](/oss/concepts/subgraphs), you only need to provide the checkpointer when compiling the parent graph. LangGraph will automatically propagate the checkpointer to the child subgraphs.
 
 :::python
 ```python {highlight={16,21,25}}

src/oss/langgraph/functional-api.mdx

@@ -898,7 +898,7 @@ Providing non-serializable inputs or outputs will result in a runtime error when
 
 To utilize features like **human-in-the-loop**, any randomness should be encapsulated inside of **tasks**. This guarantees that when execution is halted (e.g., for human in the loop) and then resumed, it will follow the same _sequence of steps_, even if **task** results are non-deterministic.
 
-LangGraph achieves this behavior by persisting **task** and [**subgraph**](/oss/subgraphs) results as they execute. A well-designed workflow ensures that resuming execution follows the _same sequence of steps_, allowing previously computed results to be retrieved correctly without having to re-execute them. This is particularly useful for long-running **tasks** or **tasks** with non-deterministic results, as it avoids repeating previously done work and allows resuming from essentially the same.
+LangGraph achieves this behavior by persisting **task** and [**subgraph**](/oss/concepts/subgraphs) results as they execute. A well-designed workflow ensures that resuming execution follows the _same sequence of steps_, allowing previously computed results to be retrieved correctly without having to re-execute them. This is particularly useful for long-running **tasks** or **tasks** with non-deterministic results, as it avoids repeating previously done work and allows resuming from essentially the same.
 
 While different runs of a workflow can produce different results, resuming a **specific** run should always follow the same sequence of recorded steps. This allows LangGraph to efficiently look up **task** and **subgraph** results that were executed prior to the graph being interrupted and avoid recomputing them.
 

src/oss/langgraph/graph-api.mdx

@@ -899,7 +899,7 @@ Check out this [how-to guide](/oss/langgraph/graph-api.md#combine-control-flow-a
 ### Navigating to a node in a parent graph
 
 :::python
-If you are using [subgraphs](/oss/subgraphs), you might want to navigate from a node within a subgraph to a different subgraph (i.e. a different node in the parent graph). To do so, you can specify `graph=Command.PARENT` in `Command`:
+If you are using [subgraphs](/oss/concepts/subgraphs), you might want to navigate from a node within a subgraph to a different subgraph (i.e. a different node in the parent graph). To do so, you can specify `graph=Command.PARENT` in `Command`:
 
 ```python
 def my_node(state: State) -> Command[Literal["other_subgraph"]]:
@@ -922,7 +922,7 @@ When you send updates from a subgraph node to a parent graph node for a key that
 :::
 
 :::js
-If you are using [subgraphs](/oss/subgraphs.md), you might want to navigate from a node within a subgraph to a different subgraph (i.e. a different node in the parent graph). To do so, you can specify `graph: Command.PARENT` in `Command`:
+If you are using [subgraphs](/oss/concepts/subgraphs.md), you might want to navigate from a node within a subgraph to a different subgraph (i.e. a different node in the parent graph). To do so, you can specify `graph: Command.PARENT` in `Command`:
 
 ```typescript
 import { Command } from "@langchain/langgraph";
@@ -947,7 +947,7 @@ When you send updates from a subgraph node to a parent graph node for a key that
 :::
 
 :::js
-If you are using [subgraphs](/oss/subgraphs.md), you might want to navigate from a node within a subgraph to a different subgraph (i.e. a different node in the parent graph). To do so, you can specify `graph: Command.PARENT` in `Command`:
+If you are using [subgraphs](/oss/concepts/subgraphs.md), you might want to navigate from a node within a subgraph to a different subgraph (i.e. a different node in the parent graph). To do so, you can specify `graph: Command.PARENT` in `Command`:
 
 ```typescript
 import { Command } from "@langchain/langgraph";

src/oss/langgraph/overview.mdx

@@ -91,7 +91,7 @@ LangGraph provides low-level supporting infrastructure for *any* long-running, s
 
 * [Durable execution](/oss/langgraph/durable-execution): Build agents that persist through failures and can run for extended periods, resuming from where they left off.
 * [Human-in-the-loop](/oss/langgraph/add-human-in-the-loop): Incorporate human oversight by inspecting and modifying agent state at any point.
-* [Comprehensive memory](/oss/memory): Create stateful agents with both short-term working memory for ongoing reasoning and long-term memory across sessions.
+* [Comprehensive memory](/oss/concepts/memory): Create stateful agents with both short-term working memory for ongoing reasoning and long-term memory across sessions.
 * [Debugging with LangSmith](/langsmith/home): Gain deep visibility into complex agent behavior with visualization tools that trace execution paths, capture state transitions, and provide detailed runtime metrics.
 * [Production-ready deployment](/langgraph-platform/deployment-options): Deploy sophisticated agent systems confidently with scalable infrastructure designed to handle the unique challenges of stateful, long-running workflows.
 

src/oss/langgraph/persistence.mdx

@@ -1167,7 +1167,7 @@ First, checkpointers facilitate [human-in-the-loop workflows](/oss/langgraph/add
 
 ### Memory
 
-Second, checkpointers allow for ["memory"](/oss/memory) between interactions. In the case of repeated human interactions (like conversations) any follow up messages can be sent to that thread, which will retain its memory of previous ones. See [Add memory](/oss/langgraph/add-memory) for information on how to add and manage conversation memory using checkpointers.
+Second, checkpointers allow for ["memory"](/oss/concepts/memory) between interactions. In the case of repeated human interactions (like conversations) any follow up messages can be sent to that thread, which will retain its memory of previous ones. See [Add memory](/oss/langgraph/add-memory) for information on how to add and manage conversation memory using checkpointers.
 
 ### Time Travel