You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[`docs dev` not working / running](#docs-dev-not-working--running)
@@ -39,7 +33,16 @@
39
33
40
34
---
41
35
42
-
## Repository structure
36
+
## Contribute
37
+
38
+
To contribute to LangChain documentation, follow the steps outlined in the [contributing guide](/oss/contributing/documentation). The contributing guide also explains our documentation types and their writing and quality standards.
39
+
40
+
> [!IMPORTANT]
41
+
> For contributing to reference docs, see the `README.md` file in the `/reference/python` and `/reference/javascript` directories.
The Mintlify docs pipeline is structured with `.mdx` source files in `/src` and build artifacts in `/build`. Mintlify deploys from the `/build` folder, which is generated by preprocessing logic.
69
72
@@ -72,200 +75,21 @@ The Mintlify docs pipeline is structured with `.mdx` source files in `/src` and
72
75
73
76
The `/src/docs.json` file is used to configure the Mintlify site navigation and settings. Refer to the [Mintlify documentation](https://www.mintlify.com/docs/organize/navigation) for detailed syntax and component usage.
74
77
75
-
Documentation changes follow a PR [workflow](#workflow) where all tests must pass before merging.
78
+
Documentation changes follow a PR workflow where all tests must pass before merging. See the [contributing guidelines](/oss/contributing/documentation) for more details.
76
79
77
-
### `reference.langchain.com`
80
+
####`reference.langchain.com`
78
81
79
82
Each language has its own build pipeline in `/reference/<language>`. Reference docs are built with a combination of automated docstring extraction and manually written content. Refer to the `README.md` in each folder for details on how to build and contribute.
80
83
81
84
Built files are stored in `/reference/dist/{LANGUAGE}`, which is then deployed to Vercel. The build process is triggered automatically on pushes to `main` and can also be triggered manually via the Vercel dashboard.
82
85
83
-
---
84
-
85
-
## Contributing
86
-
87
-
Before making any changes, we encourage you to read the LangChain [contributing guide](https://docs.langchain.com/oss/python/contributing/documentation) to understand our documentation types and their writing and quality standards.
88
-
89
-
> [!IMPORTANT]
90
-
> The following steps refer to the [`docs.langchain.com`](https://docs.langchain.com) Mintlify documentation site. For contributing to reference docs, see the `README.md` file in the `/reference/python` and `/reference/javascript` directories.
91
-
92
-
### Set up a local dev environment
93
-
94
-
1. Clone this repo. Follow the steps outlined in [IDE_SETUP.md](./IDE_SETUP.md).
95
-
2. Install `uv` from <https://docs.astral.sh/uv/> (if not already installed)
96
-
3. Install `npm` from <https://nodejs.org/en/download/> (if not already installed)
97
-
4. Create and activate a virtual environment:
98
-
99
-
```bash
100
-
cd docs
101
-
uv venv
102
-
source .venv/bin/activate
103
-
```
104
-
105
-
5. Install dependencies:
106
-
107
-
```bash
108
-
uv sync --all-groups
109
-
```
110
-
111
-
```bash
112
-
npm i -g mint
113
-
```
114
-
115
-
After install, you'll have access to the `docs` command:
116
-
117
-
```bash
118
-
docs --help
119
-
```
120
-
121
-
Common commands:
122
-
123
-
*`docs dev` - Start development mode with file watching and hot reload
124
-
*`docs build` - Build documentation
125
-
126
-
See [Available commands](#available-commands) for more details.
127
-
128
-
### Workflow
129
-
130
-
> [!IMPORTANT]
131
-
> ***Only edit files in `src/`** - The `build/` directory is automatically generated
132
-
> ***Use Mintlify syntax** - See [Mintlify documentation](https://mintlify.com/docs) for formatting guidelines
133
-
134
-
1. Ensure your [dev environment is set up](#set-up-local-dev-environment) and that you have followed the steps in [IDE_SETUP.md](./IDE_SETUP.md) to configure your IDE/editor to automatically apply the correct settings.
135
-
136
-
2. Start development mode:
137
-
138
-
```bash
139
-
docs dev
140
-
```
141
-
142
-
This starts a development server with hot reload at <http://localhost:3000>.
143
-
144
-
3. Edit files in `src/`:
145
-
* Make changes to markdown files, notebooks, or other documentation
146
-
* The build system automatically detects changes and rebuilds affected files
147
-
* If OSS content varies between Python and JavaScript/TypeScript, add content for [both in the same file](#co-locate-python-and-javascripttypescript-oss-content). Otherwise, content will be identical for both languages.
148
-
* If [adding localized content](#localized-content), add content in the specific language directory (e.g.,`src/ko/` for Korean).
149
-
150
-
4. Use `docs dev` to [preview changes](#create-a-preview-build) locally with hot reload. Changes automatically appear in your browser at <http://localhost:3000>.
151
-
152
-
5. Iterate:
153
-
* Continue editing and see changes reflected immediately.
154
-
* The development server rebuilds only changed files for faster feedback.
155
-
156
-
6. Run the [quality checks](#quality-checks) to ensure your changes are valid.
157
-
158
-
7.[Publish to production](#publish-to-prod) (internal team members only).
159
-
160
-
### Co-locate Python and JavaScript/TypeScript OSS content
161
-
162
-
In the `/oss` directory, we have a custom syntax for co-locating Python and JavaScript/TypeScript content in the same file. Use the `:::python` and `:::js` code language fences to tag the content that is specific to that language and will generate two outputs (one for each language). These are closed with the `:::` fence.
163
-
164
-
For example, if you have a file in `/oss/concepts/foo.mdx`, you can use the following syntax to co-locate Python and JavaScript/TypeScript content:
165
-
166
-
```mdx
167
-
:::python
168
-
This is Python-specific content.
169
-
:::
170
-
171
-
:::js
172
-
This is JavaScript/TypeScript-specific content.
173
-
:::
174
-
```
175
-
176
-
This will generate two outputs (one for each language) at `/oss/python/concepts/foo.mdx` and `/oss/javascript/concepts/foo.mdx`. Each outputted page will need to be added to the `/src/docs.json` file to be included in the navigation.
177
-
178
-
### Localized content
179
-
180
-
> [!IMPORTANT]
181
-
> Currently, the LangChain documentation is only available in English, but we are working to add support for other languages, thanks to our LangChain Ambassadors!
182
-
183
-
To add localized content (content in a specific language), place it in the corresponding language directory. Each language has its own directory named after its language code. For more information, refer to the [Mintlify documentation](https://www.mintlify.com/docs/organize/navigation#languages) for more details on localized content.
184
-
185
-
```text
186
-
src/
187
-
langsmith/ # English - LangSmith docs
188
-
oss/ # English - LangChain, LangGraph, Deep Agents, and integrations docs
189
-
...
190
-
cn/ # Chinese (Simplified) - No content yet
191
-
es/ # Spanish - No content yet
192
-
ko/ # Korean - No content yet
193
-
zh-Hant/ # Chinese (Traditional) - No content yet
194
-
```
195
-
196
-
### Create a preview build
197
-
198
-
When you create or update a PR, a [preview branch/ID](https://github.com/langchain-ai/docs/actions/workflows/create-preview-branch.yml) is automatically generated for you. A comment will be left on the PR with the ID, which you can then use to generate a preview. You can also run this workflow manually if needed. Previews are useful for sharing work-in-progress changes with others.
199
-
200
-
1. Copy the preview branch's ID from the comment.
201
-
2. In the [Mintlify dashboard](https://dashboard.mintlify.com/langchain-5e9cc07a/langchain-5e9cc07a?section=previews), click **Create preview deployment**.
202
-
3. Enter the preview branch's ID.
203
-
4. Click **Create deployment**.
204
-
A **Manual update** will display in the **Previews** table.
205
-
5. Select the preview and click **Visit** to view the preview build.
206
-
207
-
To redeploy the preview build, click **Redeploy** on the Mintlify dashboard.
208
-
209
-
210
-
### Quality checks
211
-
212
-
Before submitting changes, ensure your code passes formatting and linting checks:
213
-
214
-
```bash
215
-
# Check broken links
216
-
make mint-broken-links
217
-
218
-
# Format code automatically
219
-
make format
220
-
221
-
# Check for linting issues
222
-
make lint
223
-
224
-
# Fix markdown issues
225
-
make lint_md_fix
226
-
227
-
# Run tests to ensure your changes don't break existing functionality
228
-
make test
229
-
```
230
-
231
-
> [!IMPORTANT]
232
-
> All pull requests are automatically checked by CI/CD.
233
-
>
234
-
> The same linting and formatting standards will be enforced, and PRs cannot be merged if these checks fail.
235
-
236
-
### Publish to prod
237
-
238
-
> [!IMPORTANT]
239
-
> Only internal team members can publish to production.
240
-
241
-
Once your branch has been merged into `main`, you need to push the changes to `prod` for them to render on the live docs site. Use the [Publish documentation GH action](https://github.com/langchain-ai/docs/actions/workflows/publish.yml):
242
-
243
-
1. Go to [Publish documentation](https://github.com/langchain-ai/docs/actions/workflows/publish.yml).
244
-
2. Click the **Run workflow** button.
245
-
3. Select the **main** branch to deploy.
246
-
4. Click **Run workflow**.
247
-
248
-
## Reference
249
-
250
86
### File formats
251
87
252
88
***Markdown files** (`.md`, `.mdx`) - Standard documentation content
253
89
***Snippets** (`src/snippets/`) - Reusable MDX content that can be imported into multiple pages. **Important:** Snippets undergo special link preprocessing. When writing links in snippets, be careful about path segments.
254
90
***Jupyter notebooks** (`.ipynb`) - Converted to markdown during build, though **these are not recommended for new content!** Your PR will likely be rejected if you attempt to add a Jupyter notebook unless asked to by a maintainer.
255
91
***Assets** - Images and other files are copied to the build directory
256
92
257
-
### Documentation syntax
258
-
259
-
Our primary docs the [Mintlify](https://mintlify.com/docs) platform for docs generation. Key features include:
260
-
261
-
***Frontmatter** - YAML metadata at the top of files
262
-
***Components** - Special Mintlify components for enhanced formatting
263
-
***Code blocks** - Syntax highlighting and copy functionality
264
-
***Navigation** - Automatic sidebar generation from file structure
265
-
***Code language fences** (only used in `/oss`) - 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).
266
-
267
-
Refer to the [Mintlify documentation](https://mintlify.com/docs) for detailed syntax and component usage.
268
-
269
93
### Available commands
270
94
271
95
**Make commands:**
@@ -314,9 +138,6 @@ These can be used directly using the `Makefile` or via the `docs` CLI tool:
314
138
***`docs build`** - Build documentation files
315
139
*`--watch` - Watch for file changes after building
0 commit comments