Skip to content

Commit 5f2e1ea

Browse files
prrao87prrao87
committed
Create writing guide
1 parent 20be2fb commit 5f2e1ea

1 file changed

Lines changed: 201 additions & 0 deletions

File tree

‎WRITING.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Writing guide
2+
3+
This is a documentation site built in [Mintlify](https://www.mintlify.com/docs). Writing in Mintlify is similar to `README.md`
4+
docs you may be used to writing in markdown -- the main difference is that Mintlify uses MDX files (Markdown + JSX) files
5+
instead of regular markdown files.
6+
7+
It's worth going through the key sections in the Mintlify [docs](https://www.mintlify.com/docs) before you begin writing.
8+
To begin writing, create a new MDX file in the appropriate location and follow the steps below.
9+
10+
## 1. Create the MDX file
11+
12+
As far as possible, docs are organized at the top level by concept, in the `/docs/` directory. In certain cases,
13+
an additional level of nesting into an inner subdirectory is okay to avoid cluttering in the sidebar. However, it's
14+
recommended to avoid nesting more than 2 levels deep as this affects the flow and discoverability from a user
15+
perspective.
16+
17+
## 2. Update `docs.json`
18+
19+
The sitemap is defined in JSON format in `docs.json`. You can organize new content into tab groups and pages, as per the
20+
structure shown in the existing `docs.json`. To view the new page in the sidebar and in the local preview, it must be
21+
referenced in `docs.json` in the appropriate location.
22+
23+
## 3. Add frontmatter
24+
25+
Frontmatter is written in YAML, and is compulsory for all MDX files that contain documentation. It's recommended to _always_
26+
have at least the first three keys (`title`, `sidebarTitle` and `description`) for readability and SEO on a given docs page.
27+
Specifying an `icon` helps readers associate a familiar image with the page title in the sidebar. For searchability within
28+
the docs, you can optionally specify the `keywords` field and pass in a list of keyword strings. When a user searches for
29+
those strings, the page is prioritized in the search box.
30+
31+
Here's an example:
32+
33+
```yml
34+
---
35+
title: "Lance format"
36+
sidebarTitle: "Lance format"
37+
description: "Open-source lakehouse format for multimodal AI."
38+
icon: "/static/assets/logo/lance-logo-gray.svg"
39+
keywords: ["lance"]
40+
---
41+
```
42+
43+
> ![NOTE]
44+
> The example above showed a custom SVG icon in the `/static/assets/` directory of this repo, but you can pick stock
45+
> icons from [fontawesome.com](https://fontawesome.com/icons) by searching for a high-level concept by name.
46+
47+
## 4. Begin writing
48+
49+
Writing in Mintlify is similar to conventional markdown, except that you have access to JSX-based (React) components that
50+
make it much simple to add documentation-friendly functionality and aesthetics to the docs page. Components are a very powerful
51+
addition to the writing experience, and are covered in detail on the [Mintlify docs](https://www.mintlify.com/docs/components/accordions).
52+
53+
Below is an example of a `Card`, which emphasizes content, while providing a clickable URL out of the given page.
54+
```jsx
55+
<Card
56+
title="Quickstart"
57+
icon="rocket"
58+
href="/quickstart"
59+
>
60+
Get started with LanceDB in minutes.
61+
</Card>
62+
```
63+
64+
The best part about components is that they are composable. You can embed one component inside another and achieve the functionality of both. The example below shows an `Card` at the top level, with an `Accordion` inside it.
65+
66+
```mdx
67+
<Card
68+
title="Quickstart"
69+
icon="rocket"
70+
href="/quickstart"
71+
>
72+
Get started with LanceDB in minutes.
73+
74+
<Accordion>
75+
Collapsible text content here....
76+
</Accordion>
77+
78+
</Card>
79+
```
80+
81+
## 5. Mathematical equations
82+
83+
Math equations are supported via standard KaTeX plugins. You can write any LaTeX-style equation and get it rendered on the
84+
page by enclosing it in `$$` symbols.
85+
86+
```
87+
$$
88+
E = mc^2
89+
$$
90+
```
91+
92+
## 6. Code snippets
93+
94+
Code snippets are where Mintlify probably differs the most from markdown. There are several ways to write code snippets, but
95+
this section describes how we do it specifically in these LanceDB docs.
96+
97+
### Option 1: `CodeGroup` components
98+
99+
The preferred way to include a code snippet is to enter it within <CodeGroup> tags, as follows:
100+
101+
```mdx
102+
<CodeGroup>
103+
```python Python icon="python"
104+
import lancedb
105+
```
106+
107+
```typescript TypeScript icon="square-js"
108+
import * as lancedb from "@lancedb/lancedb";
109+
```
110+
111+
```rust Rust icon="rust"
112+
use lancedb::connect;
113+
```
114+
</CodeGroup>
115+
```
116+
117+
This will allow you to include code snippets from multiple languages, grouped together on the docs page so that the user
118+
can click on their language of choice via tabs.
119+
120+
### Option 2: `CodeBlock` components within `CodeGroup`
121+
122+
As engineers, we may want to write a testable snippet in code in the `tests/py`, `tests/ts`, or `tests/rs` directory.
123+
These directories contain test files in each language that contain valid, tested code, which are fenced within comment markers
124+
so that they can be parsed by a [snippet generation script](./scripts/mdx_snippets_gen.py).
125+
126+
The snippet generation script is run to extract the relevant snippets from the file (based on the fenced comment markers
127+
indicating `start` and `end` in each test file).
128+
129+
Here's how you'd call the snippet into a code block in the MDX file:
130+
131+
```mdx
132+
import { PyConnect, TsConnect, RsConnect } from '/snippets/connection.mdx';
133+
134+
<CodeGroup >
135+
<CodeBlock filename="Python" language="Python" icon="python">
136+
{PyConnect}
137+
</CodeBlock>
138+
139+
<CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
140+
{TsConnect}
141+
</CodeBlock>
142+
143+
<CodeBlock filename="Rust" language="Rust" icon="rust">
144+
{ "// Rust imports go here\n" }
145+
{RsConnect}
146+
</CodeBlock>
147+
</CodeGroup >
148+
149+
```
150+
151+
### Option 3: Vanilla backticks
152+
153+
This is the least preferred approach, as it doesn't let you group together code snippets from multiple languages effectively.
154+
Note that Mintlify offers some additional features compared to traditional markdown even when using triple backticks.
155+
156+
In the example below, we may have a long code snippet that we want to collapse (to show a few lines in the rendered page).
157+
This is useful for example code or data snippets that are quite long.
158+
159+
```json camelot.json icon="brackets-curly" expandable=true
160+
[
161+
{
162+
"id": 1,
163+
"name": "King Arthur",
164+
"role": "King of Camelot",
165+
"description": "The legendary ruler of Camelot, wielder of Excalibur, and leader of the Knights of the Round Table.",
166+
"vector": [0.72, -0.28, 0.60, 0.86],
167+
"stats": { "strength": 2, "courage": 5, "magic": 1, "wisdom": 4 }
168+
}
169+
]
170+
```
171+
172+
Using vanilla backticks is okay when the code snippets like JSON blobs can get really long, and we only want to show a
173+
preview to the reader. Enabling `expandable=true` allows readers to see the whole block when they click on the "expand"
174+
button on the page.
175+
176+
## 7. Run local deployment
177+
178+
After you update the `docs.json` page with the path to the new MDX file, you can debug the site on the local deployment.
179+
180+
```bash
181+
# cd to the docs/ directory
182+
cd docs
183+
# Run local server
184+
mint dev
185+
```
186+
This will run a local deployment on `localhost:3000`, which is useful for debugging and testing purposes.
187+
188+
You can check for broken lines in the site by running the following command.
189+
190+
```bash
191+
mint broken-links
192+
```
193+
194+
> ![NOTE]
195+
> The broken link checker **only** checks for internal (relative) links to other pages within this docs repo.
196+
> It cannot check external site links.
197+
198+
## 8. Commit to the docs repo
199+
200+
Once you've finished writing and reviewing the content yourself, submit a PR to the [repo](https://github.com/lancedb/docs)
201+
for review. If you're an external contributor, we thank you for your contribution to LanceDB!

0 commit comments

Comments
 (0)