|
1 | 1 | # Contribution guide |
2 | 2 |
|
3 | | -This guide covers how to contribute to the Ably docs repository. From general pull request processes, to how to update and use each textile component. |
| 3 | +This guide covers how to contribute to the Ably docs repository, including general pull request processes and content formatting. |
4 | 4 |
|
5 | 5 | ## Pull request process |
6 | 6 |
|
@@ -35,12 +35,12 @@ There are two main locations that contributors need to work with to varying exte |
35 | 35 |
|
36 | 36 | | Folder | Contains | |
37 | 37 | | ------ | -------- | |
38 | | -| content | All content pages written in textile. | |
39 | | -| src | Images, navigation and language version and management. | |
| 38 | +| how-tos | Tutorial content in MDX format. | |
| 39 | +| src | Images, navigation, and language version management. | |
40 | 40 |
|
41 | | -## Textile format |
| 41 | +## Content format |
42 | 42 |
|
43 | | -The following sections discuss how to write and implement each component using textile. |
| 43 | +Documentation pages use MDX format for content. The following sections discuss common formatting patterns. |
44 | 44 |
|
45 | 45 | ### Metadata |
46 | 46 |
|
@@ -73,19 +73,17 @@ An example heading (with a custom anchor link) is: `h2(#subscribe). Subscribe to |
73 | 73 |
|
74 | 74 | ### Links |
75 | 75 |
|
76 | | -Links in textile are written in quotation marks. Link text can also be [code styled](#in-line-code). |
| 76 | +Use standard Markdown link syntax: `[link text](url)`. |
77 | 77 |
|
78 | 78 | #### Internal links |
79 | 79 |
|
80 | | -To link to another heading on the same page use the anchor link: `"channel state changes":#listen-for-state`. |
| 80 | +To link to another docs page use: `[messages](/docs/channels/message)`. |
81 | 81 |
|
82 | | -To link to another docs page use: `"messages":/docs/channels/message`. |
83 | | - |
84 | | -You may also use in-line code to style link text: `"@get()@":/docs/api/realtime-sdk/channels#get method` |
| 82 | +To link to a heading on the same page: `[channel state changes](#listen-for-state)`. |
85 | 83 |
|
86 | 84 | #### External links |
87 | 85 |
|
88 | | -To link externally, or outside of the docs repository, use a fully qualified link: `"Ably dashboard":https://ably.com/dashboard`. |
| 86 | +Use fully qualified URLs: `[Ably dashboard](https://ably.com/dashboard)`. |
89 | 87 |
|
90 | 88 | > Note: for dashboard links you can use `/any/` as the account ID to link directly to a specific page. For example: `https://ably.com/accounts/any/edit` for the account settings page. |
91 | 89 |
|
@@ -164,7 +162,7 @@ To make a cell span two columns: |
164 | 162 |
|
165 | 163 | ### Admonitions |
166 | 164 |
|
167 | | -There are three types of admonition that can be used; `note`, `important` and `further-reading`. Update the value of `data-type` to switch between them. Admonitions are written using the HTML `<aside>` tag. Content must be constructed in HTML, other than links and in-line code styling which accept textile format. |
| 165 | +There are three types of admonition that can be used; `note`, `important` and `further-reading`. Update the value of `data-type` to switch between them. Admonitions are written using the HTML `<aside>` tag with HTML or Markdown content. |
168 | 166 |
|
169 | 167 | ```html |
170 | 168 | <aside data-type='note'> |
@@ -198,7 +196,7 @@ Textile accepts several formats for unordered lists, however `*` should be used |
198 | 196 | * Mint Choc Chip |
199 | 197 | ``` |
200 | 198 |
|
201 | | -For ordered lists, textile will accept any number before a `.` and order it appropriately. Ascending numbers should be used for readability and consistency. |
| 199 | +For ordered lists, use standard Markdown syntax with ascending numbers for readability and consistency. |
202 | 200 |
|
203 | 201 | ```plaintext |
204 | 202 | 1. Cornetto |
@@ -329,7 +327,7 @@ bq(definition). |
329 | 327 |
|
330 | 328 | ### Partials |
331 | 329 |
|
332 | | -API references make use of [partials](content/partials/) where content is reused between files. They are included in .textile files using the following syntax: |
| 330 | +API references previously used partials for reusable content. This functionality has been replaced with component-based content reuse. |
333 | 331 |
|
334 | 332 | ```plaintext |
335 | 333 | <%= partial partial_version('realtime/_stats') %> |
|
0 commit comments