Skip to content

Commit c390ad4

Browse files
authored
Merge pull request #2030 from appwrite/docs-content-and-style
Document content and style guidance
2 parents 61a19d0 + e47c850 commit c390ad4

File tree

2 files changed

+31
-24
lines changed

2 files changed

+31
-24
lines changed

CONTENT.md

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,10 @@
11
# Content Guidelines
22

3-
## Table of Contents
4-
5-
### Basics
3+
## Basics
64

75
Here are some essential markdoc syntax elements with code examples:
86

9-
#### Paragraphs and Line Breaks
7+
### Paragraphs and Line Breaks
108

119
To create a new paragraph, simply leave a blank line between lines of text.
1210

@@ -16,7 +14,7 @@ This is the first paragraph.
1614
This is the second paragraph.
1715
```
1816

19-
#### Headers
17+
### Headers
2018

2119
Headers are used to create section titles. Use hashtags (#) for headers, with more hashtags for lower-level headers.
2220

@@ -34,7 +32,7 @@ Headers can also be given ID's so they can be linked to and are present in the T
3432
# Header with ID {% #header-with-id %}
3533
```
3634

37-
#### Lists
35+
### Lists
3836

3937
Create ordered (numbered) and unordered (bulleted) lists using 1., \*, or -.
4038

@@ -54,7 +52,7 @@ Create ordered (numbered) and unordered (bulleted) lists using 1., \*, or -.
5452
- Cherry
5553
```
5654

57-
#### Links
55+
### Links
5856

5957
Create hyperlinks to other web pages or sections within your documentation.
6058

@@ -63,7 +61,7 @@ Create hyperlinks to other web pages or sections within your documentation.
6361
[Link to Section](#section-name)
6462
```
6563

66-
#### Images
64+
### Images
6765

6866
Embed images using the `![alt text](image URL)` syntax.
6967

@@ -82,7 +80,7 @@ In most cases, we need images in both light and dark mode such as:
8280
{% /only_light %}
8381
```
8482

85-
#### Code Blocks
83+
### Code Blocks
8684

8785
Format code blocks using triple backticks (```).
8886

@@ -95,15 +93,15 @@ def hello_world():
9593

9694
Remember to use a specific language label if the code is using an Appwrite SDK. Find the [list of available labels here](https://github.com/appwrite/website/blob/41bb6c71a8647016c88393003d3cf6c4edba1f76/src/lib/utils/references.ts#L26).
9795

98-
#### Inline Code
96+
### Inline Code
9997

10098
Highlight inline code with backticks (`) around the code snippet.
10199

102100
```md
103101
Use the `print()` function to display text.
104102
```
105103

106-
#### Emphasis and Strong Text
104+
### Emphasis and Strong Text
107105

108106
Use asterisks (\*) or underscores (\_) for emphasis and double asterisks or underscores for strong text.
109107

@@ -114,7 +112,7 @@ _Italic Text_ or _Italic Text_
114112
**Bold Text** or **Bold Text**
115113
```
116114

117-
#### Tables
115+
### Tables
118116

119117
Tables allow you to display structured data in your documentation. Use pipes (|) to separate columns and hyphens (-) to define the table header.
120118

@@ -146,7 +144,7 @@ Alternatively, use markdoc tables.
146144
{% /table %}
147145
```
148146

149-
#### Block Quotes
147+
### Block Quotes
150148

151149
Block quotes are used to emphasize or highlight text. To create a block quote, use the > symbol at the beginning of the quoted text.
152150

@@ -157,9 +155,9 @@ Block quotes are used to emphasize or highlight text. To create a block quote, u
157155

158156
These are the fundamental Markdown syntax elements you'll need to create well-structured and formatted documentation.
159157

160-
### Components
158+
## Components
161159

162-
#### Tabs
160+
### Tabs
163161

164162
```md
165163
{% tabs %}
@@ -173,7 +171,7 @@ Lorem ipsum dolor sit amet consectetur.
173171
{% /tabs %}
174172
```
175173

176-
#### Multicode Examples
174+
### Multicode Examples
177175

178176
<pre>
179177
{% multicode %}
@@ -191,7 +189,9 @@ print('test');
191189
{% /multicode %}
192190
</pre>
193191

194-
#### Sections
192+
Remember to use a specific language label if the code is using an Appwrite SDK. Find the [list of available labels here](https://github.com/appwrite/website/blob/41bb6c71a8647016c88393003d3cf6c4edba1f76/src/lib/utils/references.ts#L26).
193+
194+
### Sections
195195

196196
Use sections when there is a clear step-by-step format to a page. This is used mainly in journey pages and tutorials.
197197

@@ -209,15 +209,15 @@ Lorem ipsum dolor sit amet consectetur.
209209
{% /section %}
210210
```
211211

212-
#### Info
212+
### Info
213213

214214
```
215215
{% info title="Public Service Announcement" %}
216216
Lorem ipsum dolor sit amet consectetur.
217217
{% /info %}
218218
```
219219

220-
#### Icon
220+
### Icon
221221

222222
Available sizes are `s`, `m`, `l` and `xl`. Default: `s`.
223223

@@ -228,7 +228,7 @@ Available sizes are `s`, `m`, `l` and `xl`. Default: `s`.
228228
{% icon icon="github" size="xl" /%}
229229
```
230230

231-
#### Icon Image
231+
### Icon Image
232232

233233
Available sizes are `s`, `m`, `l` and `xl`. Default: `s`.
234234

@@ -239,7 +239,7 @@ Available sizes are `s`, `m`, `l` and `xl`. Default: `s`.
239239
{% icon_image src="/icon.png" alt="Icon" size="xl" /%}
240240
```
241241

242-
#### Only Light/Dark Theme
242+
### Only Light/Dark Theme
243243

244244
```
245245
{% only_dark %}
@@ -250,7 +250,7 @@ Available sizes are `s`, `m`, `l` and `xl`. Default: `s`.
250250
{% /only_light %}
251251
```
252252

253-
#### Cards
253+
### Cards
254254

255255
We use cards when we reference a list of links for navigation
256256

@@ -276,7 +276,7 @@ Get started with Appwrite and SvelteKit
276276
{% /cards %}
277277
```
278278

279-
#### Cards with icons
279+
### Cards with icons
280280

281281
We use cards when we reference a list of links for navigation, this variation has icons for extra hints visually.
282282

@@ -294,7 +294,7 @@ Configure FCM for push notification to Android and Apple devices.
294294
{% /cards %}
295295
```
296296

297-
#### Accordions
297+
### Accordions
298298

299299
Use accordions to reduce page size and collapse information that's not important when a reader is scrolling the page.
300300

STYLE.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -332,6 +332,13 @@ or a page needs to be sufficiently different from existing pages, follow exisitn
332332

333333
If you are proposing a new type of page, discuss an outline in your PR and ask for the Appwrite team's review.
334334

335+
### Placeholders
336+
337+
Whenever there's a need for a placeholder such as for an ID, use angle brackets (<>) over square brackets ([]) because square brackets can be confused for an array.
338+
339+
-`client.setEndpoint("https://<REGION>.cloud.appwrite.io")`
340+
-`client.setEndpoint("https://[REGION].cloud.appwrite.io")`
341+
335342
## Code snippets
336343

337344
For quick starts and tutorials, a developer must be able to follow code examples from beginning to end

0 commit comments

Comments
 (0)