WEBDIENSTE/langgraph
1
0
Fork 0
mirror of https://github.com/langchain-ai/langgraph.git synced 2026-09-12 20:57:52 +02:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): Consolidate hooks for copy markdown and notebooks (#5459)

Browse Source 
Consolidating the hooks to avoid duplication of logic

We need this change for consolidating js and python content: we need include-markdown to run as a mkdocs plugin before our pipeline (rather than as markdown extension which runs after our hooks plugin).
This commit is contained in:
Eugene Yurtsev
2025-07-11 20:44:46 +00:00
committed by GitHub
parent d166e9b8e9
commit f59a1339c9
19 changed files with 1629 additions and 2291 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/_scripts/copy_page_hooks.py
-162
View File
@@ -1,162 +0,0 @@
"""
Copy page functionality hooks for MkDocs.
This module provides hooks to inject original markdown content into HTML pages
for the copy page functionality, allowing users to copy clean markdown content
optimized for LLMs.
"""
import json
import re
from pathlib import Path
from typing import Optional
from mkdocs.config.defaults import MkDocsConfig
from mkdocs.structure.pages import Page
def _process_includes(content: str, docs_dir: Path) -> str:
"""Process MkDocs includes like {!../README.md!}."""
include_pattern = r'\{!([^!]+)!\}'
def replace_include(match):
include_path = match.group(1)
# Resolve relative path
if include_path.startswith('../'):
# Go up from docs dir
include_file = docs_dir.parent / include_path[3:]
else:
include_file = docs_dir / include_path
try:
with open(include_file, 'r', encoding='utf-8') as f:
included_content = f.read()
# Remove frontmatter from included content to avoid duplication
included_content = re.sub(r'^---\n.*?\n---\n', '', included_content, flags=re.DOTALL)
return included_content
except:
return f"[Content from {include_path}]"
return re.sub(include_pattern, replace_include, content)
def _clean_markdown(content: str) -> str:
"""Minimal cleanup of markdown content - preserve original as much as possible."""
# Remove frontmatter
content = re.sub(r'^---\n.*?\n---\n', '', content, flags=re.DOTALL)
# Remove script tags (security)
content = re.sub(r'<script[^>]*>.*?</script\s*>', '', content, flags=re.DOTALL | re.IGNORECASE)
# Remove style tags (security)
content = re.sub(r'<style[^>]*>.*?</style\s*>', '', content, flags=re.DOTALL | re.IGNORECASE)
# Remove HTML comments
content = re.sub(r'<!--.*?-->', '', content, flags=re.DOTALL)
# Just strip and return - preserve original structure
return content.strip()
def inject_markdown_content(html: str, page: Page, config: MkDocsConfig) -> str:
"""
Inject the original markdown content into the HTML for copy page functionality.
Args:
html: The HTML content to inject into
page: The MkDocs page object
config: The MkDocs configuration
Returns:
Modified HTML with markdown content injected as JSON
"""
if not hasattr(page, 'file') or not page.file:
return html
# Get the original markdown file path
docs_dir = Path(config.get('docs_dir', 'docs'))
src_path = page.file.src_path
# Handle different file types
if src_path.endswith('.ipynb'):
# For notebook files, we might want to use the converted markdown
# For now, just return the HTML as-is
return html
markdown_file = docs_dir / src_path
if not markdown_file.exists():
return html
try:
# Read the original markdown content
with open(markdown_file, 'r', encoding='utf-8') as f:
markdown_content = f.read()
# Special handling for index page - use relative path to the actual README.md
if src_path == 'index.md':
# Relative path to the repository README.md file (go up two levels from docs/docs)
readme_path = docs_dir.parent.parent / 'README.md'
try:
with open(readme_path, 'r', encoding='utf-8') as f:
readme_content = f.read()
# Remove frontmatter if present
processed_markdown = re.sub(r'^---\n.*?\n---\n', '', readme_content, flags=re.DOTALL)
processed_markdown = processed_markdown.strip()
except Exception as e:
# If we can't read the README, fallback to original behavior
processed_markdown = _process_includes(markdown_content, docs_dir)
processed_markdown = re.sub(r'^---\n.*?\n---\n', '', processed_markdown, flags=re.DOTALL)
processed_markdown = processed_markdown.strip()
else:
# Process any includes in the markdown to get the full content
processed_markdown = _process_includes(markdown_content, docs_dir)
# Clean up the processed markdown normally for other pages
processed_markdown = _clean_markdown(processed_markdown)
# Create the JSON data
markdown_data = {
'markdown': processed_markdown,
'title': page.title or 'Page Content',
'url': page.url or ''
}
# Properly escape the JSON for HTML
json_content = json.dumps(markdown_data, ensure_ascii=False)
json_content = json_content.replace('</', '\\u003c/')
json_content = json_content.replace('<script', '\\u003cscript')
json_content = json_content.replace('</script', '\\u003c/script')
script_content = f'<script id="page-markdown-content" type="application/json">{json_content}</script>'
# Insert before </head> if it exists, otherwise before </body>
if '</head>' in html:
html = html.replace('</head>', f'{script_content}</head>')
elif '</body>' in html:
html = html.replace('</body>', f'{script_content}</body>')
except Exception as e:
# If anything goes wrong, just return the original HTML
# Could log the error here if needed
pass
return html
def on_post_page(output: str, page: Page, config: MkDocsConfig) -> str:
"""
MkDocs hook to inject markdown content into HTML pages.
This hook is called after each page is rendered and injects the original
markdown content as JSON for the copy page functionality.
Args:
output: The HTML output of the page
page: The MkDocs page object
config: The MkDocs configuration
Returns:
Modified HTML with markdown content injected
"""
return inject_markdown_content(output, page, config)
docs/_scripts/notebook_hooks.py
+46 -10
View File
@@ -3,6 +3,7 @@
Lifecycle events: https://www.mkdocs.org/dev-guide/plugins/#events
"""
import json
import logging
import os
import posixpath
@@ -15,8 +16,8 @@ from mkdocs.structure.files import Files, File
from mkdocs.structure.pages import Page
from _scripts.generate_api_reference_links import update_markdown_with_imports
from _scripts.notebook_convert import convert_notebook
from _scripts.link_map import JS_LINK_MAP
from _scripts.notebook_convert import convert_notebook
logger = logging.getLogger(__name__)
logging.basicConfig()
@@ -356,12 +357,16 @@ def _on_page_markdown_with_config(
def on_page_markdown(markdown: str, page: Page, **kwargs: Dict[str, Any]):
return _on_page_markdown_with_config(
markdown,
page,
add_api_references=True,
**kwargs,
finalized_markdown = (
_on_page_markdown_with_config(
markdown,
page,
add_api_references=True,
**kwargs,
)
)
page.meta["original_markdown"] = finalized_markdown
return finalized_markdown
# redirects
@@ -431,20 +436,51 @@ height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
else:
return html # fallback if no <body> found
def _inject_markdown_into_html(html: str, page: Page) -> str:
"""Inject the original markdown content into the HTML page as JSON."""
original_markdown = page.meta.get("original_markdown", "")
if not original_markdown:
return html
markdown_data = {
"markdown": original_markdown,
"title": page.title or "Page Content",
"url": page.url or "",
}
def on_post_page(output: str, page: Page, config: MkDocsConfig) -> str:
# Properly escape the JSON for HTML
json_content = json.dumps(markdown_data, ensure_ascii=False)
json_content = (
json_content.replace("</", "\\u003c/")
.replace("<script", "\\u003cscript")
.replace("</script", "\\u003c/script")
)
script_content = (
f'<script id="page-markdown-content" '
f'type="application/json">{json_content}</script>'
)
# Insert before </head> if it exists, otherwise before </body>
if "</head>" not in html:
raise ValueError(
"HTML does not contain </head> tag. Cannot inject markdown content."
)
return html.replace("</head>", f"{script_content}</head>")
def on_post_page(html: str, page: Page, config: MkDocsConfig) -> str:
"""Inject Google Tag Manager noscript tag immediately after <body>.
Args:
output: The HTML output of the page.
html: The HTML output of the page.
page: The page instance.
config: The MkDocs configuration object.
Returns:
modified HTML output with GTM code injected.
"""
return _inject_gtm(output)
html = _inject_markdown_into_html(html, page)
return _inject_gtm(html)
# Create HTML files for redirects after site dir has been built
def on_post_build(config):
docs/docs/agents/models.md
+1 -1
View File
@@ -7,7 +7,7 @@ LangGraph provides built-in support for [LLMs (language models)](https://python.
Use [`init_chat_model`](https://python.langchain.com/docs/how_to/chat_models_universal_init/) to initialize models:
{!snippets/chat_model_tabs.md!}
{% include-markdown "../../snippets/chat_model_tabs.md" %}
### Instantiate a model directly
docs/docs/how-tos/graph-api.md
+1 -1
View File
@@ -1507,7 +1507,7 @@ Because many LangChain objects implement the [Runnable Protocol](https://python.
See example below. To demonstrate async invocations of underlying LLMs, we will include a chat model:
{!snippets/chat_model_tabs.md!}
{% include-markdown "../../snippets/chat_model_tabs.md" %}
```python
from langchain.chat_models import init_chat_model
docs/docs/how-tos/memory/semantic-search.ipynb
+1 -1
View File
@@ -125,7 +125,7 @@
"memories = store.search((\"user_123\", \"memories\"), query=\"I like food?\", limit=5)\n",
"\n",
"for memory in memories:\n",
" print(f'Memory: {memory.value[\"text\"]} (similarity: {memory.score})')"
" print(f\"Memory: {memory.value['text']} (similarity: {memory.score})\")"
]
},
{
docs/docs/index.md
+1 -1
View File
@@ -28,4 +28,4 @@ title: LangGraph
}
</style>
{!../README.md!}
{% include-markdown "../../README.md" %}
docs/docs/snippets/chat_model_tabs.md
+87
View File
@@ -0,0 +1,87 @@
=== "OpenAI"
```shell
pip install -U "langchain[openai]"
```
```python
import os
from langchain.chat_models import init_chat_model
os.environ["OPENAI_API_KEY"] = "sk-..."
llm = init_chat_model("openai:gpt-4.1")
```
👉 Read the [OpenAI integration docs](https://python.langchain.com/docs/integrations/chat/openai/)
=== "Anthropic"
```shell
pip install -U "langchain[anthropic]"
```
```python
import os
from langchain.chat_models import init_chat_model
os.environ["ANTHROPIC_API_KEY"] = "sk-..."
llm = init_chat_model("anthropic:claude-3-5-sonnet-latest")
```
👉 Read the [Anthropic integration docs](https://python.langchain.com/docs/integrations/chat/anthropic/)
=== "Azure"
```shell
pip install -U "langchain[openai]"
```
```python
import os
from langchain.chat_models import init_chat_model
os.environ["AZURE_OPENAI_API_KEY"] = "..."
os.environ["AZURE_OPENAI_ENDPOINT"] = "..."
os.environ["OPENAI_API_VERSION"] = "2025-03-01-preview"
llm = init_chat_model(
"azure_openai:gpt-4.1",
azure_deployment=os.environ["AZURE_OPENAI_DEPLOYMENT_NAME"],
)
```
👉 Read the [Azure integration docs](https://python.langchain.com/docs/integrations/chat/azure_chat_openai/)
=== "Google Gemini"
```shell
pip install -U "langchain[google-genai]"
```
```python
import os
from langchain.chat_models import init_chat_model
os.environ["GOOGLE_API_KEY"] = "..."
llm = init_chat_model("google_genai:gemini-2.0-flash")
```
👉 Read the [Google GenAI integration docs](https://python.langchain.com/docs/integrations/chat/google_generative_ai/)
=== "AWS Bedrock"
```shell
pip install -U "langchain[aws]"
```
```python
from langchain.chat_models import init_chat_model
# Follow the steps here to configure your credentials:
# https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html
llm = init_chat_model(
"anthropic.claude-3-5-sonnet-20240620-v1:0",
model_provider="bedrock_converse",
)
```
👉 Read the [AWS Bedrock integration docs](https://python.langchain.com/docs/integrations/chat/bedrock/)
docs/docs/tutorials/get-started/1-build-basic-chatbot.md
+1 -1
View File
@@ -63,7 +63,7 @@ Next, add a "`chatbot`" node. **Nodes** represent units of work and are typicall
Let's first select a chat model:
{!snippets/chat_model_tabs.md!}
{% include-markdown "../../../snippets/chat_model_tabs.md" %}
<!---
```python
docs/docs/tutorials/get-started/2-add-tools.md
+2 -2
View File
@@ -73,7 +73,7 @@ For the `StateGraph` you created in the [first tutorial](./1-build-basic-chatbot
Let's first select our LLM:
{!snippets/chat_model_tabs.md!}
{% include-markdown "../../../snippets/chat_model_tabs.md" %}
<!---
```python
@@ -286,7 +286,7 @@ For ease of use, adjust your code to replace the following with LangGraph prebui
- `BasicToolNode` is replaced with the prebuilt [ToolNode](https://langchain-ai.github.io/langgraph/reference/prebuilt/#toolnode)
- `route_tools` is replaced with the prebuilt [tools_condition](https://langchain-ai.github.io/langgraph/reference/prebuilt/#tools_condition)
{!snippets/chat_model_tabs.md!}
{% include-markdown "../../../snippets/chat_model_tabs.md" %}
```python hl_lines="25 30"
docs/docs/tutorials/get-started/3-add-memory.md
+1 -1
View File
@@ -154,7 +154,7 @@ The snapshot above contains the current state values, corresponding config, and
Check out the code snippet below to review the graph from this tutorial:
{!snippets/chat_model_tabs.md!}
{% include-markdown "../../../snippets/chat_model_tabs.md" %}
<!---
```python
docs/docs/tutorials/get-started/4-human-in-the-loop.md
+2 -2
View File
@@ -14,7 +14,7 @@ Starting with the existing code from the [Add memory to the chatbot](./3-add-mem
Let's first select a chat model:
{!snippets/chat_model_tabs.md!}
{% include-markdown "../../../snippets/chat_model_tabs.md" %}
<!---
```python
@@ -221,7 +221,7 @@ The input has been received and processed as a tool message. Review this call's
Check out the code snippet below to review the graph from this tutorial:
{!snippets/chat_model_tabs.md!}
{% include-markdown "../../../snippets/chat_model_tabs.md" %}
```python
from typing import Annotated
docs/docs/tutorials/get-started/5-customize-state.md
+1 -1
View File
@@ -221,7 +221,7 @@ Manual state updates will [generate a trace](https://smith.langchain.com/public/
Check out the code snippet below to review the graph from this tutorial:
{!snippets/chat_model_tabs.md!}
{% include-markdown "../../../snippets/chat_model_tabs.md" %}
<!---
```python
docs/docs/tutorials/get-started/6-time-travel.md
+1 -1
View File
@@ -14,7 +14,7 @@ You can create these types of experiences using LangGraph's built-in **time trav
Rewind your graph by fetching a checkpoint using the graph's `get_state_history` method. You can then resume execution at this previous point in time.
{!snippets/chat_model_tabs.md!}
{% include-markdown "../../../snippets/chat_model_tabs.md" %}
<!---
```python
docs/docs/tutorials/llm-compiler/LLMCompiler.ipynb
+8 -8
View File
@@ -540,11 +540,11 @@
"name": "stdout",
"output_type": "stream",
"text": [
"================================\u001B[1m System Message \u001B[0m================================\n",
"================================\u001b[1m System Message \u001b[0m================================\n",
"\n",
"Given a user query, create a plan to solve it with the utmost parallelizability. Each plan should comprise an action from the following \u001B[33;1m\u001B[1;3m{num_tools}\u001B[0m types:\n",
"\u001B[33;1m\u001B[1;3m{tool_descriptions}\u001B[0m\n",
"\u001B[33;1m\u001B[1;3m{num_tools}\u001B[0m. join(): Collects and combines results from prior actions.\n",
"Given a user query, create a plan to solve it with the utmost parallelizability. Each plan should comprise an action from the following \u001b[33;1m\u001b[1;3m{num_tools}\u001b[0m types:\n",
"\u001b[33;1m\u001b[1;3m{tool_descriptions}\u001b[0m\n",
"\u001b[33;1m\u001b[1;3m{num_tools}\u001b[0m. join(): Collects and combines results from prior actions.\n",
"\n",
" - An LLM agent is called upon invoking join() to either finalize the user query or wait until the plans are executed.\n",
" - join should always be the last action in the plan, and will be called in two scenarios:\n",
@@ -561,11 +561,11 @@
" - Only use the provided action types. If a query cannot be addressed using these, invoke the join action for the next steps.\n",
" - Never introduce new actions other than the ones provided.\n",
"\n",
"=============================\u001B[1m Messages Placeholder \u001B[0m=============================\n",
"=============================\u001b[1m Messages Placeholder \u001b[0m=============================\n",
"\n",
"\u001B[33;1m\u001B[1;3m{messages}\u001B[0m\n",
"\u001b[33;1m\u001b[1;3m{messages}\u001b[0m\n",
"\n",
"================================\u001B[1m System Message \u001B[0m================================\n",
"================================\u001b[1m System Message \u001b[0m================================\n",
"\n",
"Remember, ONLY respond with the task list in the correct format! E.g.:\n",
"idx. tool(arg_name=args)\n",
@@ -605,7 +605,7 @@
" llm: BaseChatModel, tools: Sequence[BaseTool], base_prompt: ChatPromptTemplate\n",
"):\n",
" tool_descriptions = \"\\n\".join(\n",
" f\"{i+1}. {tool.description}\\n\"\n",
" f\"{i + 1}. {tool.description}\\n\"\n",
" for i, tool in enumerate(\n",
" tools\n",
" ) # +1 to offset the 0 starting index, we want it count normally from 1.\n",
docs/docs/tutorials/plan-and-execute/plan-and-execute.ipynb
+1 -1
View File
@@ -378,7 +378,7 @@
"\n",
"async def execute_step(state: PlanExecute):\n",
" plan = state[\"plan\"]\n",
" plan_str = \"\\n\".join(f\"{i+1}. {step}\" for i, step in enumerate(plan))\n",
" plan_str = \"\\n\".join(f\"{i + 1}. {step}\" for i, step in enumerate(plan))\n",
" task = plan[0]\n",
" task_formatted = f\"\"\"For the following plan:\n",
"{plan_str}\\n\\nYou are tasked with executing step {1}, {task}.\"\"\"\n",
docs/docs/tutorials/tnt-llm/tnt-llm.ipynb
+7 -7
View File
@@ -302,7 +302,7 @@
"def format_docs(docs: List[Doc]) -> str:\n",
" xml_table = \"<conversations>\\n\"\n",
" for doc in docs:\n",
" xml_table += f'<conv_summ id={doc[\"id\"]}>{doc[\"summary\"]}</conv_summ>\\n'\n",
" xml_table += f\"<conv_summ id={doc['id']}>{doc['summary']}</conv_summ>\\n\"\n",
" xml_table += \"</conversations>\"\n",
" return xml_table\n",
"\n",
@@ -311,9 +311,9 @@
" xml = \"<cluster_table>\\n\"\n",
" for label in clusters:\n",
" xml += \" <cluster>\\n\"\n",
" xml += f' <id>{label[\"id\"]}</id>\\n'\n",
" xml += f' <name>{label[\"name\"]}</name>\\n'\n",
" xml += f' <description>{label[\"description\"]}</description>\\n'\n",
" xml += f\" <id>{label['id']}</id>\\n\"\n",
" xml += f\" <name>{label['name']}</name>\\n\"\n",
" xml += f\" <description>{label['description']}</description>\\n\"\n",
" xml += \" </cluster>\\n\"\n",
" xml += \"</cluster_table>\"\n",
" return xml\n",
@@ -600,13 +600,13 @@
" turns.append(\n",
" f\"\"\"\n",
"<human idx={idx}>\n",
"{run.inputs['question']}\n",
"{run.inputs[\"question\"]}\n",
"</human>\"\"\"\n",
" )\n",
" if run.outputs and run.outputs[\"output\"]:\n",
" turns.append(\n",
" f\"\"\"<ai idx={idx+1}>\n",
"{run.outputs['output']}\n",
" f\"\"\"<ai idx={idx + 1}>\n",
"{run.outputs[\"output\"]}\n",
"</ai>\"\"\"\n",
" )\n",
" return {\n",
docs/mkdocs.yml
+1 -3
View File
@@ -54,6 +54,7 @@ plugins:
separator: '[\s\u200b\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;'
- autorefs
- tags
- include-markdown
- mkdocstrings:
custom_templates: templates
handlers:
@@ -357,12 +358,9 @@ markdown_extensions:
combine_header_slug: true
- pymdownx.tasklist:
custom_checkbox: true
- markdown_include.include:
base_path: ./
- github-callouts
hooks:
- _scripts/notebook_hooks.py
- _scripts/copy_page_hooks.py
extra:
social:
- icon: fontawesome/brands/js
docs/pyproject.toml
+2 -1
View File
@@ -7,7 +7,7 @@ name = "langgraph-docs"
version = "0.0.1"
description = "LangGraph docs"
authors = []
requires-python = "~=3.10"
requires-python = "~=3.11"
readme = "README.md"
license = "MIT"
dependencies = [
@@ -48,6 +48,7 @@ docs = [
"ruff",
"jupyter",
"langchain-cohere",
"mkdocs-include-markdown-plugin>=7.1.6",
]
test = [
"langchain",
docs/uv.lock
Generated
+1465 -2087
View File
File diff suppressed because it is too large Load Diff