Skip to content
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions docs/contributing/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -488,3 +488,29 @@
```bash title="Hello, world!"
echo "Hello, world!"
```

### Avoiding repetition using snippets

It can be useful to repeat information on different pages to increase visibility for users.
If possible, prefer linking to a primary section describing a topic instead of fully repeating text on different pages.
However, if you believe it's beneficial to actually repeat the content, consider using [snippets](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/) to avoid repeated information getting out of sync on different pages.
Snippets allow including the contents of a text file in multiple places of the documentation.

For example, the recommended NCCL environment variables are defined in a text file (`docs/software/commuinication/nccl_env_vars`) and included on multiple pages because it's essential that users of NCCL notice and use the environment variables.

Snippets are included with `--8<-- path/to/snippet`.
For example, to include the recommended NCCL environment variables, do the following:

=== "Markdown"

````markdown
```bash
;--8<-- "docs/software/communication/nccl_env_vars"
```
````

=== "Rendered"

```bash title="Recommended NCCL environment variables"
--8<-- "docs/software/communication/nccl_env_vars"
```

Check warning on line 516 in docs/contributing/index.md

View workflow job for this annotation

GitHub Actions / Check Spelling

failed to find matching end marker for ```` ``````` (unclosed-block-ignore-begin)

Check warning on line 516 in docs/contributing/index.md

View workflow job for this annotation

GitHub Actions / Check Spelling

expected to find end block marker ```` ``````` (unclosed-block-ignore-end)
Loading