mirror of
https://github.com/coder/coder.git
synced 2026-06-02 20:48:20 +00:00
Nick Vigilante
ca337915cc
Several relative links in the docs pointed at pages that no longer exist or rendered incorrectly on coder.com. Fixes: - `start/first-template.md`: IDE links repointed from the removed `../ides.md` / `../ides/web-ides.md` to their current homes under `user-guides/workspace-access/`. - `tutorials/example-guide.md`: contributing link repointed to `../about/contributing/documentation.md`. - `about/contributing/backend.md`: the `migrations/testdata/fixtures` and `full_dumps` references (and the `000024_example.up.sql` example) used relative paths that escape `docs/` and render as bogus `/docs/coderd/...` routes on the site. Normalized to the canonical `github.com/coder/coder/(blob|tree)/main/...` form already used by ~120 other source links in the docs. - Normalized extensionless directory links (`ai-coder/ai-gateway`, `user-guides/workspace-access`, `install`) to their `/index.md` targets for consistency with the rest of the docs. This class of bug is invisible to the local doc checks (`make lint/markdown` / `pnpm check-docs` only run markdownlint + table formatting); only CI's Linkspector job validates link targets. Found via a relative-link audit while investigating the docs preview on #25816. Source-link version-awareness (so older docs versions don't all point at `main`) is tracked separately in DOCS-268 and will be handled in the coder.com render layer. Linear: DOCS-278 Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
53 lines
1.5 KiB
Markdown
53 lines
1.5 KiB
Markdown
# Guide Title (Only Visible in GitHub)
|
||
|
||
<div>
|
||
<a href="https://github.com/coder" style="text-decoration: none; color: inherit;">
|
||
<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.
|
||
|
||
## Content
|
||
|
||
Defer to our [Contributing/Documentation](../about/contributing/documentation.md) page
|
||
for rules on technical writing.
|
||
|
||
### Adding Photos
|
||
|
||
Use relative imports in the markdown and store photos in
|
||
`docs/images/guides/<your_guide>/<image>.png`.
|
||
|
||
### Setting the author data
|
||
|
||
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.
|
||
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.
|
||
|
||
## Setting up the routes
|
||
|
||
Once you've written your guide, you'll need to add its route to
|
||
`docs/manifest.json` under `Guides` > `"children"` at the bottom:
|
||
|
||
```json
|
||
{
|
||
// Overrides the "# Guide Title" at the top of this file
|
||
"title": "Contributing to Guides",
|
||
"description": "How to add a guide",
|
||
"path": "./guides/my-guide-file.md"
|
||
},
|
||
```
|
||
|
||
## 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.
|