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
Versioning allows for the maintenance of multiple versions of the same documentation, which is crucial for supporting different SDK releases. This guide explains how to create versioned documentation in the docs platform.
8
+
9
+
## Creating a Versioned Page
10
+
11
+
To create a versioned page:
12
+
13
+
1. Ensure the original page already exists.
14
+
2. Create a new file with the same name as the original, but append `__v{VERSION}` (two underscores) to the filename before the extension.
15
+
16
+
**The version should follow one of these two formats:**
17
+
- Major version only (for general version ranges): `__v{MAJOR}.x`
18
+
- Full semantic version (for specific versions): `__v{MAJOR}.{MINOR}.{PATCH}`
19
+
20
+
For example:
21
+
22
+
```
23
+
index.mdx (original)
24
+
index__v7.x.mdx (version 7.x.x)
25
+
index__v7.1.0.mdx (specific version 7.1.0)
26
+
```
27
+
28
+
29
+
## Versioning Platform Includes
30
+
31
+
Pages in the `platform-includes` folder can be versioned using the same method. However, the root page referencing these includes must also be versioned.
32
+
33
+
## File Structure Example
34
+
35
+
```
36
+
docs/
37
+
├── getting-started/
38
+
│ ├── index.mdx
39
+
│ └── index__v7.x.mdx
40
+
└── platform-includes/
41
+
└── configuration/
42
+
├── example.mdx
43
+
└── example__v7.x.mdx
44
+
```
45
+
46
+
## Version Selection and User Experience
47
+
48
+
When multiple versions of a page exist:
49
+
50
+
1. A dropdown menu appears below the platform selector, displaying all available versions for the current file.
51
+
52
+
2. When a user selects a version:
53
+
54
+
- They are redirected to the chosen version of the page.
55
+
- A preference is stored in localStorage, specific to the current guide or platform.
56
+
57
+
3. An alert is displayed when viewing "non-latest" pages to inform users they're not on the most recent version.
58
+
59
+
4. If a user has a stored version preference:
60
+
61
+
- The app will perform a client-side redirect to this version whenever it's available for other pages.
62
+
63
+
This approach ensures users can easily navigate between versions and keep their version preference across the documentation.
64
+
65
+
## Best Practices
66
+
67
+
1. Only add versioning to pages when necessary, to avoid content duplication and save build times.
68
+
2. Ensure all related content (including `platform-includes`) is versioned consistently.
69
+
70
+
71
+
## Limitations and Considerations
72
+
73
+
- Versioning is only available for existing pages.
74
+
- The versioning system relies on the file naming convention, so it's important to follow the `__v{VERSION}` format precisely.
75
+
76
+
By following these guidelines, it's possible to effectively manage multiple versions of documentation, ensuring users can access the appropriate information for their specific version of the software or API.
0 commit comments