Skip to content

Conversation

innocenzi
Copy link
Member

@innocenzi innocenzi commented Aug 10, 2025

This pull request updates how the versioning of docs works.

Instead of having a content directory with all copies of all versions, we have a docs:pull command that fetches documentation from tempestphp/tempest-framework:docs. The docs directory of the monorepository should contain all the documentation.

During local development, we can do tempest docs:pull or tempest docs:pull 1.x for a specific version. During deployment, we need to do tempest docs:pull as well before static page generation.

This is mainly for improving the experience or editing docs when we support multiple versions, because it's easy to edit a file for a different version by mistake. To go ahead with this, we need to first migrate the current docs to a docs directory on the main and 2.x branches

This PR also updates the docs URLs to be immutable. We had this conversation already, but here is a summary:

  • We have immutable URLs by default (eg. /docs redirects to the current version, right now it's /1.x)
  • Outdated URLs get a noindex meta and a canonical URL to the current version (eg. if the current version is 2.x, a /1.x/foo/bar URL would get a canonical to /2.x/foo/bar)
  • This ensures saved docs page don't 404 in the future
  • This ensures search engines don't keep outdated docs in search results
  • For better UX you should use immutable URLs in your blog posts, not /docs one

@innocenzi innocenzi force-pushed the feat/versioned-docs branch from ce98472 to b34c431 Compare August 10, 2025 14:15
@innocenzi innocenzi force-pushed the feat/versioned-docs branch from b34c431 to 6f85107 Compare August 10, 2025 14:44
@brendt
Copy link
Member

brendt commented Aug 11, 2025

Couple of questions:

  • Can we make it so that pushes on the docs repo's main branch also trigger a (simplified) deployment?
  • I'm worried about local dev having to always run docs:pull. When I'm writing docs, I like to see the changes in the browser. If possible I like to see those changes in real time.
  • Do I understand correctly that the docs then always live in the docs branch in tempest/framework? Or did you mean the docs/ directory? I haven't read through the code yet, but this confused me a bit. My assumption would be that a docs/ directory makes most sense, because then we version it together with the framework. I think that's the case, but you mentioning tempestphp/tempest-framework:docs confused me (because that's the notation for a branch)

@innocenzi
Copy link
Member Author

innocenzi commented Aug 11, 2025

Can we make it so that pushes on the docs repo's main branch also trigger a (simplified) deployment?

Not sure how yet, but should be feasible yeah!

I'm worried about local dev having to always run docs:pull.

That's one step added but I think it's beneficial in the long run. We could add that to a post update hook too

When I'm writing docs, I like to see the changes in the browser. If possible I like to see those changes in real time.

Yeah good point actually... besides using the usual workflow after a pull and copy-pasting back to the main repo, I don't see a good solution here

Do I understand correctly that the docs then always live in the docs branch

I explained it bad: it's in each version's branch inside a docs subdirectory. My notation is wrong as well

@brendt
Copy link
Member

brendt commented Aug 11, 2025

Yeah good point actually... besides using the usual workflow after a pull and copy-pasting back to the main repo, I don't see a good solution here

Could we make it so that we symlink the docs folder locally? Maybe even with a command. Something like docs:symlink? Possible by passing in a path (but assuming the default path is ../tempest-framework)

I explained it bad: it's in each version's branch inside a docs subdirectory. My notation is wrong as well

I figured, but wanted to be sure. Perfect

@innocenzi
Copy link
Member Author

That's a really good idea. I implemented that, let me know!

@innocenzi innocenzi force-pushed the feat/versioned-docs branch from a86e809 to 2d196d6 Compare August 11, 2025 05:17
@innocenzi innocenzi merged commit 1029247 into main Aug 11, 2025
2 checks passed
@innocenzi innocenzi deleted the feat/versioned-docs branch August 11, 2025 14:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants