Skip to content

Add a "Guides" section to the API landing page template #40427

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chrisdavidmills merged 3 commits into from
Aug 2, 2025
Merged

Add a "Guides" section to the API landing page template #40427

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3fa49d9
Add a "Guides" section to the API landing page template
Josh-Cena Jul 18, 2025
9320dcd
Update index.md
Josh-Cena Jul 21, 2025
90d4594
Update files/en-us/mdn/writing_guidelines/page_structures/page_types/…
Josh-Cena Jul 21, 2025
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
9 changes: 8 additions & 1 deletion ...riting_guidelines/page_structures/page_types/api_landing_page_template/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,14 @@ Don't go into a lot of detail in this section, and don't include code examples.
If there are a lot of concepts to explain around this API, you should explain them in a separate "Fundamentals" or "Concepts" article (e.g., [Fundamentals of WebXR](/en-US/docs/Web/API/WebXR_Device_API/Fundamentals)).
For a practical usage guide with code examples, you should include a "Usage…" article in your API docs (e.g., [Using the WebVR API](/en-US/docs/Web/API/WebVR_API/Using_the_WebVR_API)).

To help improve content discoverability and {{Glossary("SEO")}}, keep the following tips in mind:
## Guides
Copy link
Collaborator

@hamishwillee hamishwillee Jul 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW I like the idea but I don't think it makes much "difference". After all, if you're on this page you can see the guides on the sidebar.

What would actually make a difference for users is to make the sidebar work properly and include these guides in the sidebar when you aren't on a guide page.

Copy link
Member Author

@Josh-Cena Josh-Cena Jul 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My checker requires every parent page to link to all its children. The main goal is to detect missing members on interface pages and other landing pages, but I think it provides value for this to be a general rule. The sidebar doesn't provide short descriptions about the page's content.

Copy link
Collaborator

@hamishwillee hamishwillee Jul 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I agree it is good - in particular there is an opportunity to talk about the content. My whine is because the guide isn't in the sidebar at all if you're not in a guide.

I have no objection to this at all. But since I wasn't assigned this is just a fly by :-)

Copy link
Member Author

@Josh-Cena Josh-Cena Jul 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you look at https://developer.mozilla.org/en-US/docs/Web/API/URL for example, the sidebar does indeed contain guides. This was added last month: mdn/rari#224

Copy link
Collaborator

@hamishwillee hamishwillee Jul 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's awesome. Been complaining about it for years. Ignore me then.


Include a list of guide pages under this landing page. Each DT should link to the guide page.

- Using the ... API
- : Intro paragraph of this guide page
- Guide 2
- : Intro paragraph of this guide page

## Interfaces

Expand Down