Files
coder/docs/tutorials/example-guide.md
T

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

59 lines
1.7 KiB
Markdown
Raw Normal View History

# Guide Title (Only Visible in GitHub)
2023-12-15 11:10:41 -06:00
<div>
<a href="https://github.com/coder" style="text-decoration: none; color: inherit;">
2023-12-15 11:10:41 -06:00
<span style="vertical-align:middle;">Your Name</span>
</a>
</div>
December 13, 2023
---
This is a guide on how to make Coder guides, it is not listed on our
[official tutorials page](../tutorials/index.md) in the docs. Intended for those
who don't frequently contribute documentation changes to the `coder/coder`
repository.
2023-12-15 11:10:41 -06:00
## Content
Defer to our [documentation style guide](https://github.com/coder/coder/blob/main/contributing/documentation.md) page
for rules on technical writing.
2023-12-15 11:10:41 -06:00
<a id="adding-photos"></a>
### Add photos
2023-12-15 11:10:41 -06:00
Use relative imports in the markdown and store photos in
`docs/images/guides/<your_guide>/<image>.png`.
<a id="setting-the-author-data"></a>
### Set the author data
2023-12-15 11:10:41 -06:00
At the top of this example you will find a small html snippet that nicely
renders the author's name and photo, while linking to their GitHub profile.
2023-12-15 11:10:41 -06:00
Before submitting your guide in a PR, replace `your_github_handle`,
`your_github_profile_photo_url` and "Your Name". The entire `<img>` element can
be omitted.
<a id="setting-up-the-routes"></a>
## Set up the routes
2023-12-15 11:10:41 -06:00
Once you've written your guide, you'll need to add its route to
`docs/manifest/tutorials.yml` under `children`:
2023-12-15 11:10:41 -06:00
```yaml
# The title overrides the "# Guide Title" at the top of this file.
- title: Contributing to Guides
description: How to add a guide
path: ./tutorials/my-guide-file.md
2023-12-15 11:10:41 -06:00
```
Then run `make gen/docs-manifest` to format the sidebar sources and rebuild
`docs/manifest.json`.
2023-12-15 11:10:41 -06:00
## Format before push
Before pushing your guide to github, run `make fmt` to format the files with
Prettier. Then, push your changes to a new branch and create a PR.