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
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+14-40Lines changed: 14 additions & 40 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,31 +2,7 @@
2
2
3
3
Timescale documentation is open for contribution from all community members. The current source is in this repository.
4
4
5
-
This page explains the process and guidelines to follow when contributing to Timescale documentation.
6
-
7
-
## Contribution process
8
-
9
-
You can contribute to Timescale documentation in the following ways:
10
-
11
-
-[Create an issue][docs-issues] in this repository and describe the proposed change. Our doc team will take care of it.
12
-
- Update the docs yourself and have your change reviewed and published by our doc team.
13
-
14
-
To make the contribution yourself:
15
-
16
-
1. Get the documentation source:
17
-
18
-
- No write access? [Fork this repository][github-fork].
19
-
- Already have a write access? [Clone this repository][github-clone].
20
-
21
-
2. Create a branch from `latest`, make your changes, and raise a pull request back to `latest`.
22
-
23
-
3. Sign a Contributor License Agreement (CLA).
24
-
25
-
You have to sign the CLA only the first time you raise a PR. This helps to ensure that the community is free to use your contributions.
26
-
27
-
4. Review your changes.
28
-
29
-
The documentation site is generated in a separate private repository using [Gatsby][gatsby]. Once you raise a PR for any branch, GitHub will **automatically** generate a preview for your changes and attach the link in the comments. Any new commits will be visible at the same URL. If you don't see the latest changes, try an incognito browser window. Automated builds are not available for PRs from forked repositories.
5
+
This page explains the structure and language guidelines for contributing to Timescale documentation. See the [README][readme] for how to contribute.
30
6
31
7
## Language
32
8
@@ -58,14 +34,14 @@ Each major doc section has a dedicated directory with `.md` files inside, repres
58
34
59
35
-**Troubleshooting pages** are not written as whole Markdown files, but are programmatically assembled from individual files in the`_troubleshooting` folder. Each entry describes a single troubleshooting case and its solution, and contains the following front matter:
|`title`| string |✅| The title of the troubleshooting entry, displayed as a heading above it |
64
-
|`section`| The literal string `troubleshooting`|✅| Must be `troubleshooting`, used to identify troubleshooting entries during site build |
65
-
|`products` or `topics`| array of strings |✅ (can have either or both, but must have at least one)| The products or topics related to the entry. The entry will show up on the troubleshooting pages for the listed products and topics. |
|`title`| string |✅| The title of the troubleshooting entry, displayed as a heading above it |
40
+
|`section`| The literal string `troubleshooting`|✅| Must be `troubleshooting`, used to identify troubleshooting entries during site build |
41
+
|`products` or `topics`| array of strings |✅ (can have either or both, but must have at least one)| The products or topics related to the entry. The entry shows up on the troubleshooting pages for the listed products and topics.|
66
42
|`errors`| object of form `{language: string, message: string}`|❌| The error, if any, related to the troubleshooting entry. Displayed as a code block right underneath the title. `language` is the programming language to use for syntax highlighting. |
67
-
|`keywords`| array of strings |❌| These are displayed at the bottom of every troubleshooting page. Each keyword links to a collection of all pages associated with that keyword. |
68
-
|`tags`| array of strings |❌| Concepts, actions, or things associated with the troubleshooting entry. These are not displayed in the UI, but they affect the calculation of related pages. |
43
+
|`keywords`| array of strings |❌| These are displayed at the bottom of every troubleshooting page. Each keyword links to a collection of all pages associated with that keyword. |
44
+
|`tags`| array of strings |❌| Concepts, actions, or things associated with the troubleshooting entry. These are not displayed in the UI, but they affect the calculation of related pages. |
69
45
70
46
Beneath the front matter, describe the error and its solution in regular Markdown. You can also use any other components allowed within the docs site.
71
47
@@ -114,13 +90,13 @@ To change the structure, add or delete pages in a section, modify the correspond
114
90
|`children`| Array of page entries | ❌ | Child pages of the current page. For regular pages, the children should be located in a directory with the same name as the parent. The parent is the `index.md` file in that directory. For`directory` pages, the children should be located in the same directory as the parent. |
115
91
|`pageComponents`| One of `[['featured-cards'], ['content-list']]`| ❌ | Any page that has child pages can list its children in either card or list style at the bottom of the page. Specify the desired style with this key. |
116
92
|`featuredChildren`| Array of URLs | ❌ | Similar to `pageComponents`, this displays the children of the current page, but only the selected ones. |
117
-
|`index`| string | ❌ | If a section landing page needs to be different from the `index.md` file in that directory, this field specifies the corresponding Markdown file name. |
93
+
|`index`| string | ❌ | If a section landing page needs to be different from the `index.md` file in that directory, this field specifies the corresponding Markdown file name. |
118
94
119
95
## Reuse text in multiple pages
120
96
121
97
Partials allow you to reuse snippets of content in multiple places. All partials
122
98
live in the `_partials` top-level directory. To make a new partial, create a new
123
-
`.md` file in this directory. The filename must start with an underscore. Then import it into the target page and reference in the relevant place. See [Formatting examples][formatting].
99
+
`.md` file in this directory. The filename must start with an underscore. Then import it into the target page as an `.mdx` file and reference in the relevant place. See [Formatting examples][formatting].
124
100
125
101
## Formatting
126
102
@@ -155,7 +131,7 @@ See [Formatting examples][formatting] for details.
155
131
156
132
When adding screenshots to the docs, aim for a full-screen view to provide better context. Reduce the size of your browser so there is as little wasted space as possible.
157
133
158
-
Attach the image to your issue or PR, and the doc team will upload and insert it for you.
134
+
Attach the image to your issue or PR, and the doc team uploads and inserts it for you.
159
135
160
136
## SEO optimization
161
137
@@ -178,13 +154,11 @@ To make a documentation page more visible and clear for Google:
178
154
The previous documentation source is in the deprecated repository called [docs.timescale.com-content][legacy-source].
0 commit comments