Skip to content

Introduce a "Guides" page to collect timeless content - #354

Open
sebastianbergmann wants to merge 5 commits into
ThePHPF:mainfrom
sebastianbergmann:feature/guides
Open

sebastianbergmann wants to merge 5 commits into
ThePHPF:mainfrom
sebastianbergmann:feature/guides

Conversation

@sebastianbergmann

Copy link
Copy Markdown
Collaborator

Closes #338

Timeless content such as guides is currently only published as blog posts under "News". Because the blog is sorted by date, these posts become hard to find once newer posts have been published.

This pull request adds a Guides page, as suggested in #338. The page lists those posts by topic instead of by date. The posts remain blog posts: their URLs do not change, and they still appear under News, on the tag pages, and in the Atom feed.

Changes

  • New /guides page (source/_pages/guides.html): lists every blog post whose front matter has a guide key, grouped into sections. Each entry shows the post's title, description, publication date, and authors.
  • Existing guides marked:
  • Back-link on guide posts: a post with a guide key shows "This post is part of our Guides", linking to its section of the Guides page.
  • Navigation: "Guides" is added to the desktop and mobile navigation, between "Get Involved" and "News".
  • Get Involved page: links to the Guides page from the "Contribute to PHP itself" section.

Adding a guide

Add a guide key to the post's front matter, using the key of one of the sections defined at the top of source/_pages/guides.html:

---
title: "So You Received a Security Report. Now What?"
layout: post
guide: maintaining
published_at: 19 August 2026
---

To add a new section, add an entry with a title and an intro to the sections map in source/_pages/guides.html. Sections that contain no posts are not shown.

Open questions

Blog posts are listed in reverse chronological order, which makes
timeless content such as guides hard to find once newer posts have
been published.

The new /guides page lists every blog post whose front matter has a
`guide` key, grouped into the sections defined at the top of the
page. The posts themselves remain blog posts at their existing URLs.
"How to Contribute to PHP" goes into the "Contributing to PHP"
section, "So You Received a Security Report. Now What?" and "Your
Tool Has a New Reader" go into the "Maintaining PHP projects" section.
Readers who arrive at a guide through the blog, a feed, or a search
engine learn that more guides exist and where to find them.
@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

@sebastianbergmann sebastianbergmann changed the title Feature/guides Introduce a "Guides" page to collect timeless content Nov 9, 2026
@ElizabethN

Copy link
Copy Markdown
Contributor

@mattstauffer I think the Guide on Contributing might be redundant given the new "Get Involved" page, but I would feel better about you reviewing this to make sure there aren't any collisions or conflicts with what you have open right now.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make "guides" easier to find

2 participants