Documentation style guide & build instructions (#6563)
Documentation style guide & build instructions (#6563) * Initial style guide setup * Addressing Chris' comments * Grammatical and typo fixes * Added warning about pip versions * Changed image URL to fix deploy error
Joel Hans committed
Aug 9, 2019 at 08:12 UTC
3d97a2f44c019a980d1d05a2dc7f45afdb187243
6 files changed
+506
-8
CONTRIBUTING.md
+6
-2
@@ -61,9 +61,13 @@ As the project grows, an increasing share of our time is spent on supporting thi
61
62
### Improve documentation
63
64
-All of our documentation is in markdown (.md) files inside the netdata GitHub project. All of our [HTML documentation](https://docs.netdata.cloud) is generated from these files. At the top right of each documentation page you will see a pencil, that leads you directly to the markdown file that was used to generated it. Don't be afraid to click it and edit any of these documents and submit a GitHub Pull Request with your corrections/additions.
64
+Our documentation is in need of constant improvement and expansion. As Netdata's features grow, we need to clearly explain how each feature works and document all the possible configurations. And as Netdata's community grows, we need to improve existing documentation to make it more accessible to people of all skill levels.
65
66
-We also need help to [document each chart in the default dashboard](https://github.com/netdata/netdata/issues/279).
66
+We also need to produce beginner-level tutorials on using Netdata to monitor common applications, web servers, and more.
67
+
68
+Start with the [guide for contributing to documentation](docs/contributing/contributing-documentation.md), and then review the [documentation style guide](docs/contributing/style-guide.md) for specifics on how we write our documentation.
69
+
70
+Don't be afraid to submit a pull request with your corrections or additions! We need a lot of help and are willing to guide new contributors through the process.
71
72
## Developers
73
DOCUMENTATION.md
+1
-1
@@ -37,7 +37,7 @@ Welcome! You've arrived at the documentation for Netdata. Use the links below to
37
- [Backends](backends/): Learn how to archive Netdata's real-time metrics to a time series database (like Prometheus) for long-term archiving.
38
39
40
-Visit the [contributing](CONTRIBUTING.md) page to find guides about the Netdata code of conduct, our community, and how you can get started contributing to Netdata.
40
+Visit the [contributing guide](CONTRIBUTING.md), [contributing to documentation guide](docs/contributing/contributing-documentation.md), and [documentation style guide](docs/contributing/style-guide.md) to learn more about our community and how you can get started contributing to Netdata.
41
42
43
## Subscribe for news and tips from monitoring pros
docs/contributing/contributing-documentation.md
new
+146
@@ -0,0 +1,146 @@
1
+# Contributing to documentation
2
+
3
+We welcome contributions to Netdata's already extensive documentation, which we host at [docs.netdata.cloud](https://docs.netdata.cloud/) and store inside of the [main repository](https://github.com/netdata/netdata) on GitHub.
4
+
5
+Like all contributing to all other aspects of Netdata, we ask that anyone who wants to help with documentation read and abide by the [Contributor Convenant Code of Conduct](https://docs.netdata.cloud/code_of_conduct/) and follow the instructions outlined in our [Contributing document](../../CONTRIBUTING.md).
6
+
7
+We also ask you to read our [documentation style guide](style-guide.md), which, while not complete, will give you some guidance on how we write and organize our documentation.
8
+
9
+All our documentation uses the Markdown syntax. If you're not familiar with how it works, please read the [Markdown introduction post](https://daringfireball.net/projects/markdown/) by its creator, followed by [Mastering Markdown](https://guides.github.com/features/mastering-markdown/) guide from GitHub.
10
+
11
+
12
+## How contributing to the documentation works
13
+
14
+There are two ways to contribute to Netdata's documentation:
15
+
16
+1. Edit documentation [directly in GitHub](#edit-documentation-directly-on-gitHub).
17
+2. Download the repository and [edit documentation locally](#edit-documentation-locally).
18
+
19
+Editing in GitHub is a simpler process and is perfect for quick edits to a single document, such as fixing a typo or clarifying a confusing sentence.
20
+
21
+Editing locally is more complex, as you need to download the Netdata repository and build the documentation using `mkdocs`, but allows you to better organize complex projects. By building documentation locally, you can preview your work using a local web server before you submit your PR.
22
+
23
+In both cases, you'll finish by submitting a pull request (PR). Once you submit your PR, GitHub will initiate a number of jobs, including a Netlify preview. You can use this preview to view the documentation site with your changes applied, which might help you catch any lingering issues.
24
+
25
+To continue, follow one of the paths below:
26
+
27
+- [Edit documentation directly in GitHub](#edit-documentation-directly-on-github)
28
+- [Edit documentation locally](#edit-documentation-locally)
29
+
30
+
31
+## Edit documentation directly on GitHub
32
+
33
+Start editing documentation on GitHub by clicking the small pencil icon on any page on Netdata's [documentation site](https://docs.netdata.cloud/). You can find them at the top of every page.
34
+
35
+Clicking on this icon will take you to the associated page in the `netdata/netdata` repository. Then click the small pencil icon on any documentation file (those ending in the `.md` [Markdown] extension) in the `netdata/netdata` repository.
36
+
37
+
38
+
39
+If you know where a file resides in the Netdata repository already, you can skip the step of beginning on the documentation site and go directly to GitHub.
40
+
41
+Once you've clicked the pencil icon on GitHub, you'll see a full Markdown version of the file. Make changes as you see fit. You can use the `Preview changes` button to ensure your Markdown syntax is working properly.
42
+
43
+Under the `Propose file change` header, write in a descriptive title for your requested change. Beneath that, add a concise descrition of what you've changed and why you think it's important. Then, click the `Propose file change` button.
44
+
45
+After you've hit that button, jump down to our instructions on [pull requests and cleanup](#pull-requests-and-final-steps) for your next steps.
46
+
47
+!!! note
48
+ This process will create a branch directly on the `netdata/netdata` repository, which then requires manual cleanup. If you're going to make significant documentation contributions, or contribute often, we recommend the local editing process just below.
49
+
50
+
51
+## Edit documentation locally
52
+
53
+Editing documentation locally is the preferred method for complex changes, PRs that span across multiple documents, or those that change the styling or underlying functionality of the documentation.
54
+
55
+Here is the workflow for editing documentation locally. First, create a fork of the Netdata repository, if you don't have one already. Visit the [Netdata repository](https://github.com/netdata/netdata) and click on the `Fork` button in the upper-right corner of the window.
56
+
57
+
58
+
59
+GitHub will ask you where you want to clone the repository, and once finished you'll end up at the index of your forked Netdata repository. Clone your fork to your local machine:
60
+
61
+```bash
62
+$ git clone https://github.com/YOUR-GITHUB-USERNAME/netdata.git
63
+```
64
+
65
+You can now jump into the directory and explore Netdata's structure for yourself.
66
+
67
+
68
+### Understanding the structure of Netdata's documentation
69
+
70
+All of Netdata's documentation is stored within the repository itself, as close as possible to the code it corresponds to. Many sub-folders contain a `README.md` file, which is then used to populate the documentation about that feature/component of Netdata.
71
+
72
+For example, the file at `packaging/installer/README.md` becomes `https://docs.netdata.cloud/packaging/installer/` and is our installation documentation. By co-locating it with quick-start installtion code, we ensure documentation is always tightly knit with the functions it describes.
73
+
74
+You might find other `.md` files within these directories. The `packaging/installer/` folder also contains `UPDATE.md` and `UNINSTALL.md`, which become `https://docs.netdata.cloud/packaging/installer/update/` and `https://docs.netdata.cloud/packaging/installer/uninstall/`, respectively.
75
+
76
+If the documentation you're working on has a direct correlation to some component of Netdata, place it into the correct folder and either name it `README.md` for generic documentation, or with another name for very specific instructions.
77
+
78
+#### The `docs` folder
79
+
80
+At the root of the Netdata repository is a `docs/` folder. Inside this folder we place documentation that does not have a direct relationship to a specific component of Netdata. It's where we house our [getting started guide](../GettingStarted.md), guides on [running Netdata behind Nginx](../Running-behind-nginx.md), and more.
81
+
82
+If the documentation you're working on doesn't have a direct relaionship to a component of Netdata, it can be placed in this `docs/` folder.
83
+
84
+
85
+### Make your edits
86
+
87
+Now that you're set up and understand where to find or create your `.md` file, you can now begin to make your edits. Just use your favorite editor and keep in mind our [style guide](style-guide.md) as you work.
88
+
89
+If you add a new file to the documentation, you may need to modify the `buildyaml.sh` file to ensure it's added to the site's navigation. This is true for any file added to the `docs/` folder.
90
+
91
+Be sure to periodically add/commit your edits so that you don't lose your work! We use version control software for a reason.
92
+
93
+
94
+### Build the documentation
95
+
96
+Building the documentation periodically gives you a glimpse into the final product, and is generally required if you're making changes to the table of contents.
97
+
98
+!!! attention ""
99
+ We have only tested the build process on Linux. Initial tests on OS X have been unsuccessful. Windows is fully untested at this point, but we would love to know if it works there as well!
100
+
101
+To build the documentation, you need `python`/`pip`, `mkdocs`, and `mkdocs-material` installed on your machine.
102
+
103
+Follow the [Python installation instructions](https://www.python.org/downloads/) for your machine.
104
+
105
+Use `pip`, which was installed alongside Python, to install `mkdocs` and `mkdocs-material`. Your operating system might force you to use `pip2` or `pip3` instead, dependin on which version of Python you have installed.
106
+
107
+``` bash
108
+$ pip install mkdocs mkdocs-material
109
+```
110
+
111
+??? note "Troubleshooting"
112
+ If you're having trouble with the installation of Python, `mkdocs`, or `mkdocs-material`, try looking into the `mkdocs` [installation instructions](https://squidfunk.github.io/mkdocs-material/getting-started/#installation).
113
+
114
+When `pip` is finished installing, navigate to the root directory of the Netdata repository and run the documentation generator script.
115
+
116
+``` bash
117
+$ sh docs/generator/buildhtml.sh
118
+```
119
+
120
+This process will take some time. Once finished, the built documentation site will be located at `docs/generator/build/`.
121
+
122
+
123
+### Run a local web server to test documentation
124
+
125
+The best way to view the documentation site you just built is to run a simple web server from the `docs/generator/build/` directory. So, navigate there and run a Python-based web server:
126
+
127
+```
128
+$ cd docs/generator/build/
129
+$ python3 -m http.server 20000
130
+```
131
+
132
+Feel free to replace the port number you want this web server to listen on (port `20000` in this case [only one higher than the agent!]).
133
+
134
+Open your web browser and navigate to `http://localhost:20000`. If you replaced the port earlier, change it here as well. You can now navigate through the documentation as you would on the live site!
135
+
136
+
137
+## Pull requests and final steps
138
+
139
+When you're finished with your changes, add and commit them to your fork of the Netdata repository. Head over to GitHub to create your pull request (PR).
140
+
141
+Once we receive your pull request (PR), we'll take time to read through it and assess it for correctness, conciseness, and overall quality. We may point to specific sections and ask for additional information or other fixes.
142
+
143
+
144
+## What's next
145
+
146
+- Read up on the Netdata documentation [style guide](style-guide.md).
\ No newline at end of file
docs/contributing/style-guide.md
new
+320
@@ -0,0 +1,320 @@
1
+# Netdata style guide
2
+
3
+This in-progress style guide establishes editorial guidelines for anyone who wants to write documentation for Netdata products.
4
+
5
+## Table of contents
6
+
7
+- [Welcome!](#welcome)
8
+- [Goals of the Netdata style guide](#goals-of-the-Netdata-style-guide)
9
+- [General principles](#general-principles)
10
+- [Tone and content](#tone-and-content)
11
+- [Language and grammar](#language-and-grammar)
12
+- [Markdown syntax](#markdown-syntax)
13
+- [Accessibility](#accessibility)
14
+
15
+
16
+## Welcome
17
+
18
+Proper documentation is essential to the success of any open-source project. Netdata is no different. The health of our monitoring agent, and the community it's created, depends on this effort.
19
+
20
+We’re here to make developers, sysadmins, and DevOps engineers better at their jobs, after all!
21
+
22
+We welcome contributions to Netdata's documentation. Begin with the [contributing to documentation guide](contributing-documentation.md), followed by this style guide.
23
+
24
+
25
+## Goals of the Netdata style guide
26
+
27
+An editorial style guide establishes standards for writing and maintaining documentation. At Netdata, we focus on the following principles:
28
+
29
+- Consistency
30
+- High-quality writing
31
+- Conciseness
32
+- Accessibility
33
+
34
+These principles will make documentation better for everyone who wants to use Netdata, whether they're a beginner or an expert.
35
+
36
+### Breaking the rules
37
+
38
+None of the rules described in this style guide are absolute. **We welcome rule-breaking if it creates better, more accessible documentation.**
39
+
40
+But be aware that Netdata staff or community members may ask you to justify your rule-breaking during the PR review process.
41
+
42
+## General principles
43
+
44
+Yes, this style guide is pretty overwhelming! Establishing standards for a global community is never easy.
45
+
46
+Here's a few key points to start with. Where relevant, they link to more in-depth information about a given rule.
47
+
48
+**[Tone and content](#tone-and-content)**:
49
+
50
+- Be [conversational and friendly](#conversational-and-friendly-tone).
51
+- Write [concisely](#write-concisely).
52
+- Don't use words like **here** when [creating hyperlinks](#use-informational-hyperlinks).
53
+- Don't mention [future releases or features](#mentioning-future-releases-or-features) in documentation.
54
+
55
+**[Language and grammar](#language-and-grammar)**:
56
+
57
+- [Capitalize words](#capitalization) at the beginning of sentences, for proper nouns, and at the beginning of document titles and section headers.
58
+- Use [second person](#second-person)—"you" rather than "we"—when giving instructions.
59
+- Use [active voice](#active-voice) to make clear who or what is performing an action.
60
+- Always employ an [Oxford comma](#oxford-comma) on lists.
61
+
62
+**[Markdown syntax](#markdown-syntax)**:
63
+
64
+- [Reference UI elements](#references-to-ui-elements) with bold text.
65
+- Use our [built-in syntax highlighter](#language-specific-syntax-highlighting-in-code-blocks) to improve the readability and usefulness of code blocks.
66
+
67
+**[Accessibility](#accessibility)**:
68
+
69
+- Include [alt tags on images](#images).
70
+
71
+---
72
+
73
+## Tone and content
74
+
75
+Netdata's documentation should be conversational, concise, and informational, without feeling formal. This isn't a textbook. It's a repository of information that should (on occasion!) encourage and excite its readers.
76
+
77
+By following a few principles on tone and content we'll ensure more readers from every background and skill level will learn as much as possible about Netdata's capabilities.
78
+
79
+### Conversational and friendly tone
80
+
81
+Netdata's documentation should be conversational and friendly. To borrow from Google's fantastic [developer style guide](https://developers.google.com/style/tone):
82
+
83
+> Try to sound like a knowledgeable friend who understands what the developer wants to do.
84
+
85
+Feel free to let some of your personality show! Documentation can be highly professional without being dry, formal, or overly instructive.
86
+
87
+### Write concisely
88
+
89
+You should always try to use as few words as possible to explain a particular feature, configuration, or process. Conciseness leads to more accurate and understandable writing.
90
+
91
+### Use informational hyperlinks
92
+
93
+Hyperlinks should clearly state its destination. Don't use words like "here" to describe where a link will take your reader.
94
+
95
+```
96
+# Not recommended
97
+To install Netdata, click [here](https://docs.netdata.cloud/packaging/installer/).
98
+
99
+# Recommended
100
+To install Netdata, read our [installation instructions](https://docs.netdata.cloud/packaging/installer/).
101
+```
102
+
103
+In general, guides should include fewer hyperlinks to keep the reader focused on the task at hand. Documentation should include as many hyperlinks as necessary to provide meaningful context.
104
+
105
+### Avoid words like "easy" or "simple"
106
+
107
+Never assume readers of Netdata documentation are experts in Netdata's inner workings or health monitoring/performance troubleshooting in general.
108
+
109
+If you claim that a task is easy and the reader struggles to complete it, they'll get discouraged.
110
+
111
+If you perceive one option to be easier than another, be specific about how and why. For example, don't write, "Netdata's one-line installer is the easiest way to install Netdata." Instead, you might want to say, "Netdata's one-line installer requires fewer steps than manually installing from source."
112
+
113
+### Avoid slang, metaphors, and jargon
114
+
115
+A particular word, phrase, or metaphor you're familiar with might not translate well to the other cultures featured among Netdata's global community. It's recommended you avoid slang or colloquialisms in your writing.
116
+
117
+If you must use industry jargon, such as "white-box monitoring," in a document, be sure to define the term as clearly and concisely as you can.
118
+
119
+> White-box monitoring: Monitoring of a system or application based on the metrics it directly exposes, such as logs.
120
+
121
+Avoid emojis whenever possible for the same reasons—they can be difficult to understand immediately and don't translate well.
122
+
123
+### Mentioning future releases or features
124
+
125
+Documentation is meant to describe the product as-is, not as it will be or could be in the future. Netdata documentation generally avoids talking about future features or products, even if we know they are inevitable.
126
+
127
+An exception can be made for documenting beta features that are subject to change with further development.
128
+
129
+## Language and grammar
130
+
131
+Netdata's documentation should be consistent in the way it uses certain words, phrases, and grammar. The following sections will outline the preferred usage for capitalization, point of view, active voice, and more.
132
+
133
+### Capitalization
134
+
135
+In text, follow the general [English standards](https://owl.purdue.edu/owl/general_writing/mechanics/help_with_capitals.html) for capitalization. In summary:
136
+
137
+- Capitalize the first word of every new sentence.
138
+- Don't use uppercase for emphasis. (Netdata is the BEST!)
139
+- Capitalize the names of brands, software, products, and companies according to their official guidelines. (Netdata, Docker, Apache, Nginx)
140
+- Avoid camel case (NetData) or all caps (NETDATA).
141
+
142
+#### Capitalization of 'Netdata' and 'netdata'
143
+
144
+Whenever you refer to the company Netdata, Inc., or the open-source monitoring agent the company develops, capitalize **Netdata**.
145
+
146
+However, if you are referring to a process, user, or group on a Linux system, you should not capitalize, as by default those are typically lowercased. In this case, you should also fence these terms in an inline code block: `` `netdata` ``.
147
+
148
+```
149
+# Not recommended
150
+The netdata agent, which spawns the netdata process, is actively maintained by netdata, inc.
151
+
152
+# Recommended
153
+The Netdata agent, which spawns the `netdata` process, is actively maintained by Netdata, Inc.
154
+```
155
+
156
+#### Capitalization of document titles and page headings
157
+
158
+Document titles and page headings should use sentence case. That means you should only capitalize the first word.
159
+
160
+If you need to use the name of a brand, software, product, and company, capitalize it according to their official guidelines.
161
+
162
+Also, don't put a period (`.`) or colon (`:`) at the end of a title or header.
163
+
164
+**Document titles**:
165
+
166
+| Capitalization | Not recommended | Recommended
167
+| --- | --- | ---
168
+| Document titles | Getting Started Guide | Getting started guide
169
+| Page headings | Service Discovery and Auto-Detection: | Service discovery and auto-detection
170
+| Proper nouns | Install netdata with docker | Install Netdata with Docker
171
+
172
+### Second person
173
+
174
+When writing documentation, you should use the second person ("you") to give instructions. When using the second person, you give the impression that you're personally leading your reader through the steps or tips in question.
175
+
176
+See how that works? It's a core part of making Netdata's documentation feel welcoming to all.
177
+
178
+Avoid using "we," "I," "let's," and "us" in documentation whenever possible.
179
+
180
+The "you" pronoun can also be implied, depending on your sentence structure.
181
+
182
+```
183
+# Not recommended
184
+To install Netdata, we should try the one-line installer...
185
+
186
+# Recommended
187
+To install Netdata, you should try the one-line installer...
188
+
189
+# Recommended, implied "you"
190
+To install Netdata, try the one-line installer...
191
+```
192
+
193
+### Active voice
194
+
195
+Use active voice instead of passive voice, because active voice is more concise and easier to understand.
196
+
197
+When using voice, the subject of the sentence is performing the action. In passive voice, the subject is being acted upon. A famous example of passive voice is the phrase "mistakes were made."
198
+
199
+```
200
+# Not recommended (passive)
201
+When an alarm is triggered by a metric, a notification is sent by Netdata...
202
+
203
+# Recommended (active)
204
+When a metric triggers an alarm, Netdata sends a notification...
205
+```
206
+
207
+### Standard American spelling
208
+
209
+While the Netdata team is mostly *not* American, we still aspire to use American spelling whenever possible, as it is more commonly used within the monitoring industry.
210
+
211
+### Clause order
212
+
213
+If you want to instruct your reader to take some action in a particular circumstance, such as optional steps, the beginning of the sentence should indicate that circumstance.
214
+
215
+```
216
+# Not recommended
217
+Read the reference guide if you'd like to learn more about custom dashboards.
218
+
219
+# Recommended
220
+If you'd like to learn more about custom dashboards, read the reference guide.
221
+```
222
+
223
+By placing the circumstance at the beginning of the sentence, those who don't want to follow can stop reading and move on. Those who *do* want to read it are less likely to skip over the sentence.
224
+
225
+### Oxford comma
226
+
227
+The Oxford comma is the comma used after the second-to-last item in a list of three or more items. It appears just before "and" or "or."
228
+
229
+```
230
+# Not recommended
231
+Netdata can monitor RAM, disk I/O, MySQL queries per second and lm-sensors.
232
+
233
+# Recommended
234
+Netdata can monitor RAM, disk I/O, MySQL queries per second, and lm-sensors.
235
+```
236
+
237
+
238
+## Markdown syntax
239
+
240
+The Netdata documentation uses the Markdown syntax for styling and formatting. If you're not familiar with how it works, please read the [Markdown introduction post](https://daringfireball.net/projects/markdown/) by its creator, followed by [Mastering Markdown](https://guides.github.com/features/mastering-markdown/) guide from GitHub.
241
+
242
+We also leverage the power of the [Material theme for MkDocs](https://squidfunk.github.io/mkdocs-material/), which features several [extensions](https://squidfunk.github.io/mkdocs-material/extensions/admonition/), such as the ability to create notes, warnings, and collapsible blocks.
243
+
244
+You can follow the syntax specified in the above resources for the majority of documents, but the following sections specify a few particular use cases.
245
+
246
+### References to UI elements
247
+
248
+If you need to instruct your reader to click a user interface (UI) element inside of a Netdata interface, you should reference the label text of the link/button with Markdown's (`**bold text**`) tag.
249
+
250
+```markdown
251
+Click on the **Sign in** button.
252
+```
253
+
254
+!!! note
255
+ Whenever possible, avoid using directional language to orient readers, because not every reader can use instructions like "look at the top-left corner" to find their way around an interface.
256
+
257
+ If you feel that you must use directional language, perhaps use an [image](#images) (with proper alt text) instead.
258
+
259
+ We're also working to establish standards for how we refer to certain elements of the Netdata's web interface. We'll include that in this style guide as soon as it's complete.
260
+
261
+
262
+### Language-specific syntax highlighting in code blocks
263
+
264
+Our documentation uses the [Highlight extension](https://facelessuser.github.io/pymdown-extensions/extensions/highlight/) for syntax highlighting. Highlight is fully compatible with [Pygments](http://pygments.org/), allowing you to highlight the syntax within code blocks in a number of interesting ways.
265
+
266
+For a full list of languages, see [Pygment's supported languages](http://pygments.org/languages/). Netdata documentation will use the following for the most part: `c`, `python`, `js`, `shell`, `markdown`, `bash`, `css`, `html`, and `go`. If no language is specified, the Highlight extension doesn't apply syntax highlighting.
267
+
268
+Include the language directly after the three backticks (`` ``` ``) that start the code block. For highlighting C code, for example:
269
+
270
+````
271
+```c
272
+inline char *health_stock_config_dir(void) {
273
+ char buffer[FILENAME_MAX + 1];
274
+ snprintfz(buffer, FILENAME_MAX, "%s/health.d", netdata_configured_stock_config_dir);
275
+ return config_get(CONFIG_SECTION_HEALTH, "stock health configuration directory", buffer);
276
+}
277
+```
278
+````
279
+
280
+And the prettified result:
281
+
282
+```c
283
+inline char *health_stock_config_dir(void) {
284
+ char buffer[FILENAME_MAX + 1];
285
+ snprintfz(buffer, FILENAME_MAX, "%s/health.d", netdata_configured_stock_config_dir);
286
+ return config_get(CONFIG_SECTION_HEALTH, "stock health configuration directory", buffer);
287
+}
288
+```
289
+
290
+You can also use the Highlight and [SuperFences](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/) extensions together to show line numbers or highlight specific lines.
291
+
292
+Display line numbers by appending `linenums="1"` after the language declaration, replacing `1` with the starting line number of your choice. Highlight lines by appending `hl_lines="2"`, replacing `2` with the line you'd like to highlight. Or, multiple lines: `hl_lines="1 2 4 12`.
293
+
294
+!!! note
295
+ Line numbers and highlights are not compatible with GitHub's Markdown parser, and thus will only be viewable on our [documentation site](https://docs.netdata.cloud/). They should be used sparingly and only when necessary.
296
+
297
+## Accessibility
298
+
299
+Netdata's documentation should be as accessible as possible to as many people as possible. While the rules about [tone and content](#tone-and-content) and [language and grammar](#language-and-grammar) are helpful to an extent, we also need some additional rules to improve the reading experience for all readers.
300
+
301
+
302
+### Images
303
+
304
+Images are an important component to documentation, which is why we have a few rules around their usage.
305
+
306
+Perhaps most importantly, don't use only images to convey instructions. Each image should be accompanied by alt text and text-based instructions to ensure that every reader can access the information in the best way for them.
307
+
308
+#### Alt text
309
+
310
+Provide alt text for every image you include in Netdata's documentation. It should summarize the intent and content of the image.
311
+
312
+In Markdown, use the standard image syntax, `![]()`, and place the alt text between the brackets `[]`. Here's an example using our logo:
313
+
314
+```
315
+
316
+```
317
+
318
+#### Images of text
319
+
320
+Don't use images of text, code samples, or terminal output. Instead, put that text content in a code block so that all devices can render it clearly and screen readers can parse it.
\ No newline at end of file
docs/generator/buildyaml.sh
+10
-3
@@ -104,7 +104,8 @@ markdown_extensions:
104
- pymdownx.details
105
- pymdownx.highlight:
106
pygments_style: manni
107
- noclasses: true
107
+ css_class: "highlight codehilite"
108
+ linenums_style: pymdownx-inline
109
- pymdownx.inlinehilite
110
- pymdownx.magiclink
111
- pymdownx.mark
@@ -271,13 +272,19 @@ navpart 2 web/api/badges "" "" 2
272
navpart 2 web/api/health "" "" 2
273
navpart 2 web/api/queries "" "Queries" 2
274
274
-echo -ne "- Additional Info:
275
+echo -ne "- Contributing to Netdata:
276
+ - CONTRIBUTING.md
277
+ - 'docs/contributing/contributing-documentation.md'
278
+ - 'docs/contributing/style-guide.md'
279
- CODE_OF_CONDUCT.md
280
- CONTRIBUTORS.md
281
- packaging/maintainers/README.md
282
"
283
+
284
+echo -ne "- Additional information:
285
+"
286
navpart 2 packaging/makeself "" "" 4
287
navpart 2 libnetdata "" "libnetdata" 4
288
navpart 2 contrib
289
navpart 2 tests "" "" 2
283
-navpart 2 diagrams/data_structures
290
+navpart 2 diagrams/data_structures
\ No newline at end of file
docs/generator/custom/css/netdata.css
+23
-2
@@ -14,7 +14,6 @@
14
15
/* Custom styling for the new documentation homepage.
16
In particular, the three buttons for install/getting started/configuration. */
17
-
17
.homepage-nav {
18
display: flex;
19
margin-top: 1.4rem;
@@ -64,11 +63,33 @@
63
margin-bottom: 6rem;
64
}
65
67
-/* Make sure inline code in tables doesn't break. */
66
+/* Make sure inline code in tables don't break. */
67
.md-typeset__table code {
68
word-break: normal;
69
}
70
71
+/* Give code blocks a little more line height */
72
+.md-typeset pre {
73
+ line-height: 1.6;
74
+}
75
+
76
+/* Show line numbers. */
77
+[data-linenos]:before {
78
+ border-right: .0625rem solid #ddd;
79
+ color: #999;
80
+ content: attr(data-linenos);
81
+ display: inline-block;
82
+ margin-left: -1.2rem;
83
+ margin-right: .7rem;
84
+ padding-left: 1.2rem;
85
+}
86
+
87
+.md-typeset .highlight .hll {
88
+ display: inline;
89
+ margin: 0;
90
+ padding: 0;
91
+}
92
+
93
/* Bold the first item on the docs sidebar: Netdata Documentation */
94
.md-nav--primary > .md-nav__list > .md-nav__item:first-of-type {
95
font-weight: 700;