docs
docs copied to clipboard
wptide
Refactor to mimic wp-cli docs process
See: https://github.com/wp-cli/handbook/. Specifically:
All documentation is imported automatically into WordPress.org in a two step process:
- WordPress reads commands-manifest.json or handbook-manifest.json to understand all pages that need to be created.
- Each WordPress page has a markdown_source attribute specifying a Markdown file to be fetched, converted to HTML, and saved in the database.
For make.wordpress.org/cli, the import process is a WordPress plugin running a WP Cron job every 15 minutes. For developer.wordpress.org/cli, this is a class in the devhub theme running a WP Cron job every 12 hours.
Our current docs site is being spun up quickly for WCEU, but as we look to refactor that to be a more maintainable site we should consider recommendations from other WP teams. We can check with the Meta and Support teams to see if they have any best practice recommendations.
Per bugscrub today, we're keeping this in the 1.0.0 release as it's part of the work that is still left to fix the build process for the docs site.
There's also a wp-github-sync plugin (and a couple other plugins/theme tweaks) that could be used to keep markdown files in a GitHub repo synchronized with posts in WordPress. I've functionally proven that in a local environment and personal repo, so if we decide to alter our process and stop using docpress then I've found another option for us.
Right now we've got the docs in a pretty good place and probably will not be making this change.
I worked on refactoring the docs to remove docpress and simplify to GitHub Pages, just waiting on the GitHub Pages deployment process to catch up to all my commits. My forked repo is here: https://github.com/jeffpaul/docs. Sample docs site is here: https://jeffpaul.github.io/docs/. If I can get things cleaned up a bit (once GitHub Pages deploys catch up to my commits), then I’ll open a PR to merge my changes upstream and we can assign the wptide.org domain to the GitHub Page and be done with the docpress mess.
