docs Proposed migration of CakePHP docs to Markdown and VitePress

Following the initial steps to migrate the Sphinx/RST documentation to Markdown, as seen in the 5.x-vitepress branch and on the generated newbook site, I'm requesting feedback and collaboration on the next phases of this project.

The scripted conversion effort is nearing completion and is now producing pretty clean Markdown files. I've been focused on tackling some key conversion challenges.

✅ Migration checklist

[x] Convert Sphinx :ref: cross-references to relative links with page titles.
[x] Convert Sphinx :doc: directives to relative links with page titles.
[x] Process Sphinx :toctree: directives to build table-of-contents with page titles.
[x] Detect code block languages and format them with backticks and syntax identifiers.
[x] Convert Sphinx 'relative' links to standard relative links.
[x] Combine Sphinx php:namespace, php:class, and php:method expressions into fully qualified domain name (FQDN) strings.
[x] Add support for styled versionadded and versionchanged blocks.
[ ] Decide on existing translations (i have some reservations I'll detail below).
[ ] Decide on documentation generator, vitepress, docusaurus, ...
[ ] Decide on EPUB/PDF documentations, should we drop these?
[ ] Decide on theming
[ ] Other requirements ?

⏭️ Next Steps

Of course, an automated conversion can only take you so far. When the switch to Markdown is decided, it would require a small effort from the team to go through each page (at least for 5.x) and check for inconsistencies. There are some code blocks that couldn't be identified correctly and would require too many hacks to fix in the script; doing this with some manual labor would be more efficient.

We've provisionally used VitePress to render the new documentation. It's been incredibly easy to set up and extend, but it's not a hard requirement. The choice of the documentation tool can be revisited if a better alternative is identified.

🎨 Theming

We need a clear strategy for theming. While we can easily adjust the light mode to match the official CakePHP color scheme, there is no predefined brand guide for a dark mode.

I have already added the official CakePHP colors to the VitePress theme. For dark mode, I've used a very dark shade of the official color as a background. However, it would be beneficial to have a discussion and decide on a unified approach. What are the preferred steps for defining a dark mode theme?

🌎 Translations

I am hesitant about how to handle translations. While I could convert the current translations as they are, I'm not convinced this is the most effective or modern solution for project internationalization in 2025.

Given the maturity of AI-powered translation tools, relying solely on user-contributed translations may not be the most efficient approach. I propose we simplify this process by adding an AI translation step to the documentation pipeline for the English-language documents. What are your thoughts on this?

✨ Post-Migration Enhancements

Beyond the initial conversion, we have an opportunity to improve the overall user experience by leveraging modern Markdown features. These post-migration steps would involve manual adjustments to the converted files.

We can add line highlighting to code blocks to draw attention to specific lines or sections of code. We can also introduce code groups (tabbed code blocks) to present code examples in multiple languages or configurations within a single, organized space. These features will make the documentation more user-friendly and easier to read.

🤝 Unifying Documentation for Official Plugins

Currently, documentation for official plugins like migrations, authentication, and authorization exists on separate sites. This leads to a fragmented user experience and presents a theming and maintenance challenge.

My idea is to merge these documentations into the main documentation build pipeline. This would allow them to be rendered within the main documentation site under a unified theme, providing a single, consistent resource for developers. What would be the best way to structure this to keep the plugin docs easily accessible while making them feel like a cohesive part of the main manual?

Note: The Lua conversion scripts and the initial sidebar navigation were largely generated using AI tools (opencode + claude).

Your input and thoughts about this project are greatly appreciated.

Sep 18 '25 07:09 josbeir

Decide on existing translations (i have some reservations I'll detail below).

Drop em!

Decide on EPUB/PDF documentations, should be drop these?

If whatever new tool we switch to can easily generate either epub/pdf then we can keep it else having only the web version is fine by me.

Decide on theming

We need to maintain the CakePHP branding and have the same color scheme and fonts like the existing book / main site.

Sep 18 '25 08:09 ADmad

We need a clear strategy for theming. While we can easily adjust the light mode to match the official CakePHP color scheme, there is no predefined brand guide for a dark mode.

I have already added the official CakePHP colors to the VitePress theme. For dark mode, I've used a very dark shade of the official color as a background. However, it would be beneficial to have a discussion and decide on a unified approach. What are the preferred steps for defining a dark mode theme?

I can help with the theming, as I've implemented it a few times now. As for dark mode, you're right there is no documented standard as we've not had any sites with dark mode before. I'm happy if we ship something and iterate on it.

Decide on EPUB/PDF documentations, should be drop these?

I have no data on how frequently these are used, but I think we can start off without them. It doesn't seem to be an option with other large popular PHP frameworks, perhaps they are no longer relevant.

My idea is to merge these documentations into the main documentation build pipeline. This would allow them to be rendered within the main documentation site under a unified theme, providing a single, consistent resource for developers. What would be the best way to structure this to keep the plugin docs easily accessible while making them feel like a cohesive part of the main manual?

How about as sidebar sections under a 'plugins' heading? This gives us a place to put all our plugins together. I'm curious on how you're thinking of implementing this. How would versioning work? Part of the complexity today is an artifact of how the repositories are structured.

Given the maturity of AI-powered translation tools, relying solely on user-contributed translations may not be the most efficient approach. I propose we simplify this process by adding an AI translation step to the documentation pipeline for the English-language documents. What are your thoughts on this?

No, LLM based translations. If the community doesn't have resources to maintain a translation, we can remove it. I would ask that we retain the Japanese translation. That community has frequently put in the effort to maintain their translation, and we should do our part to port it to the new build system.

We've provisionally used VitePress to render the new documentation. It's been incredibly easy to set up and extend, but it's not a hard requirement. The choice of the documentation tool can be revisited if a better alternative is identified.

I don't have any strong opinions here. Lets continue with what you have and see how it goes.

Sep 19 '25 03:09 markstory