Skip to content

Commit d3eedda

Browse files
devin-ai-integration[bot]chdeskurdevalog
authored
Document codeblock deep-linking feature (#1472)
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Co-authored-by: Catherine Deskur <[email protected]> Co-authored-by: Catherine Deskur <[email protected]> Co-authored-by: Devin Logan <[email protected]>
1 parent 735f357 commit d3eedda

File tree

3 files changed

+220
-5
lines changed

3 files changed

+220
-5
lines changed

‎fern/products/docs/docs.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,10 @@ navigation:
111111
- page: Conditionally rendered content
112112
hidden: true
113113
path: ./pages/component-library/custom-components/conditional-rendering.mdx
114+
- page: Component demos
115+
hidden: true
116+
path: ./pages/component-library/demo.mdx
117+
slug: demo
114118
- section: AI features
115119
contents:
116120
- link: Ask Fern

‎fern/products/docs/pages/component-library/default-components/code-blocks.mdx‎

Lines changed: 98 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
title: 'Code Blocks'
33
description: 'Learn how to enhance your documentation with customizable code blocks featuring syntax highlighting, line highlighting, focusing, and more.'
4+
max-toc-depth: 2
45
---
56

67
Fern uses [Shiki](https://shiki.matsu.io/) for syntax highlighting in code blocks.
@@ -303,15 +304,107 @@ To disable scrolling and wrap overflow onto the next line, use the `wordWrap` pr
303304
</Tabs>
304305

305306

307+
## Deep linking
308+
309+
You can make specific text within code blocks clickable by defining a `links` map. This is useful for linking to documentation, API references, or related resources directly from your code examples.
310+
311+
The `links` property accepts a map where keys are matching patterns (exact strings or regex) and values are the URLs to link to.
312+
313+
### Exact string matching
314+
315+
<Tabs>
316+
<Tab title="Example">
317+
<CodeBlock
318+
links={{"PlantClient": "/learn/docs/writing-content/demo#plantclient", "createPlant": "/learn/docs/writing-content/demo#createplant"}}
319+
>
320+
```typescript
321+
import { PlantClient } from "@plantstore/sdk";
322+
323+
const client = new PlantClient({ apiKey: "YOUR_API_KEY" });
324+
const plant = await client.createPlant({
325+
name: "Monstera",
326+
species: "Monstera deliciosa"
327+
});
328+
```
329+
</CodeBlock>
330+
</Tab>
331+
<Tab title="Markdown">
332+
````markdown
333+
<CodeBlock
334+
links={{"PlantClient": "/learn/docs/writing-content/demo#plantclient", "createPlant": "/learn/docs/writing-content/demo#create_plant"}}
335+
>
336+
```typescript
337+
import { PlantClient } from "@plantstore/sdk";
338+
339+
const client = new PlantClient({ apiKey: "YOUR_API_KEY" });
340+
const plant = await client.createPlant({
341+
name: "Monstera",
342+
species: "Monstera deliciosa"
343+
});
344+
```
345+
</CodeBlock>
346+
````
347+
</Tab>
348+
</Tabs>
349+
350+
<Note>
351+
The `links` property uses JSON format. Each key in the map is matched exactly against text in the Code Block, and matching text becomes a clickable link to the corresponding URL.
352+
</Note>
353+
354+
### Regex pattern matching
355+
356+
You can use regex patterns for more flexible matching. This is useful when you want to link multiple variations or patterns of text.
357+
358+
In the example below, the pattern `/get\\w+/` matches both `getPlant` and `getGarden`, while `/Plant(Store|Client)/` matches both `PlantStore` and `PlantClient`.
359+
360+
<Tabs>
361+
<Tab title="Example">
362+
<CodeBlock
363+
links={{"/get\\w+/": "/learn/docs/writing-content/demo#get-methods", "/Plant(Store|Client)/": "/learn/docs/writing-content/demo#type-definitions"}}
364+
>
365+
```python
366+
from plantstore import PlantStore, PlantClient
367+
368+
store = PlantStore(api_key="YOUR_API_KEY")
369+
client = PlantClient(store)
370+
371+
plant = store.getPlant(plant_id="123")
372+
garden = store.getGarden(garden_id="456")
373+
```
374+
</CodeBlock>
375+
</Tab>
376+
<Tab title="Markdown">
377+
````markdown
378+
<CodeBlock
379+
links={{"/get\\w+/": "/learn/docs/writing-content/demo#get-methods", "/Plant(Store|Client)/": "/learn/docs/writing-content/demo#type-definitions"}}
380+
>
381+
```python
382+
from plantstore import PlantStore, PlantClient
383+
384+
store = PlantStore(api_key="YOUR_API_KEY")
385+
client = PlantClient(store)
386+
387+
plant = store.getPlant(plant_id="123")
388+
garden = store.getGarden(garden_id="456")
389+
```
390+
</CodeBlock>
391+
````
392+
</Tab>
393+
</Tabs>
394+
395+
<Note>
396+
When using regex patterns, remember to escape special characters with double backslashes (e.g., `\\w+`, `\\d+`) in the JSON string.
397+
</Note>
398+
306399
## Combining props
307400

308-
You can combine the `title`, `highlight`, `focus`, `startLine`, `maxLines`, and `wordWrap`
401+
You can combine the `title`, `highlight`, `focus`, `startLine`, `maxLines`, `wordWrap`, and `links`
309402
props to create a code block with a title, highlighted lines, specific starting line,
310-
and a maximum height.
403+
a maximum height, and clickable links.
311404

312405
<Tabs>
313406
<Tab title="Example">
314-
```javascript title="Hello, World!" {6-8} maxLines=5 startLine={4}
407+
```javascript title="Hello, World!" {6-8} maxLines=5 startLine={4} links={{"console": "/learn/docs/writing-content/demo"}}
315408
console.log("Line 1");
316409
console.log("Line 2");
317410
console.log("Line 3");
@@ -325,8 +418,8 @@ and a maximum height.
325418
```
326419
</Tab>
327420
<Tab title = "Markdown">
328-
````markdown maxLines=5
329-
```javascript title="Hello, World!" {6-8} maxLines=5 startLine={4}
421+
````markdown
422+
```javascript title="Hello, World!" {6-8} maxLines=5 startLine={4} links={{"console": "/learn/docs/writing-content/demo"}}
330423
console.log("Line 1");
331424
console.log("Line 2");
332425
console.log("Line 3");

‎fern/products/docs/pages/component-library/demo.mdx‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: Component demos
3+
hidden: true
4+
---
5+
6+
This page contains demo content for testing and showcasing various documentation components. It's hidden from navigation but can be linked to from examples.
7+
8+
## API client examples
9+
10+
### PlantClient
11+
12+
The `PlantClient` class is the main entry point for interacting with the Plant Store API. It handles authentication, request management, and provides access to all API endpoints.
13+
14+
**Constructor parameters:**
15+
- `apiKey` (string, required): Your API authentication key
16+
- `baseUrl` (string, optional): Custom API base URL for testing
17+
- `timeout` (number, optional): Request timeout in milliseconds
18+
19+
**Example usage:**
20+
```typescript
21+
import { PlantClient } from "@plantstore/sdk";
22+
23+
const client = new PlantClient({
24+
apiKey: "your-api-key-here"
25+
});
26+
```
27+
28+
### PlantConfig
29+
30+
Configuration object for customizing the Plant Store SDK behavior.
31+
32+
**Properties:**
33+
- `retryAttempts` (number): Number of retry attempts for failed requests
34+
- `cacheEnabled` (boolean): Enable response caching
35+
- `logLevel` (string): Logging verbosity level
36+
37+
### createPlant
38+
39+
Creates a new plant entry in the database.
40+
41+
**Parameters:**
42+
- `name` (string, required): Common name of the plant
43+
- `species` (string, required): Scientific species name
44+
- `description` (string, optional): Plant description
45+
- `careLevel` (string, optional): Care difficulty level
46+
47+
**Returns:** Promise resolving to the created plant object
48+
49+
**Example:**
50+
```typescript
51+
const plant = await client.createPlant({
52+
name: "Monstera",
53+
species: "Monstera deliciosa",
54+
careLevel: "easy"
55+
});
56+
```
57+
58+
## API method examples
59+
60+
### create_plant
61+
62+
Python method for creating a new plant entry.
63+
64+
**Signature:**
65+
```python
66+
def create_plant(
67+
name: str,
68+
species: str,
69+
description: Optional[str] = None,
70+
care_level: Optional[str] = None
71+
) -> Plant
72+
```
73+
74+
### fetchPlants
75+
76+
Retrieves a list of plants from the API with optional filtering.
77+
78+
**Parameters:**
79+
- `filters` (object, optional): Filter criteria
80+
- `limit` (number, optional): Maximum number of results
81+
- `offset` (number, optional): Pagination offset
82+
83+
**Returns:** Promise resolving to an array of plant objects
84+
85+
## Type definitions
86+
87+
### PlantStore
88+
89+
The `PlantStore` class manages plant data storage and retrieval operations.
90+
91+
**Constructor parameters:**
92+
- `apiKey` (string, required): Your API authentication key
93+
- `config` (PlantConfig, optional): Configuration options
94+
95+
### PlantClient
96+
97+
The `PlantClient` class provides a client interface for interacting with PlantStore.
98+
99+
**Constructor parameters:**
100+
- `store` (PlantStore, required): PlantStore instance to use
101+
102+
### PlantResponse
103+
104+
Response object returned from plant-related API calls.
105+
106+
**Properties:**
107+
- `plants` (Array): List of plant objects
108+
- `total` (number): Total count of plants
109+
- `hasMore` (boolean): Whether more results are available
110+
111+
## Get methods
112+
113+
Common retrieval methods for accessing plant store resources.
114+
115+
| Method | Description | Parameters | Returns |
116+
|--------|-------------|------------|---------|
117+
| `getPlant` | Retrieves a single plant by its ID | `plant_id` (string, required): The unique identifier of the plant | Plant object |
118+
| `getGarden` | Retrieves a single garden by its ID | `garden_id` (string, required): The unique identifier of the garden | Garden object |

0 commit comments

Comments
 (0)