WordPress.org

Making WordPress.org

Opened 10 months ago

Last modified 4 days ago

#3593 new enhancement

Centralize GitHub Markdown importer

Reported by: schlessera Owned by:
Milestone: Priority: normal
Component: Handbooks Keywords:
Cc:

Description

There are currently a few teams that want GitHub Markdown importing to feed their handbook: CLI, REST API, Gutenberg, WPCS, and probably more to come in the future, I think it would be worth a small refactoring effort to produce a reusable plugin that handle this across all teams & sites.

@rmccue has already done a lot of preliminary work for making this reusable in https://github.com/WP-API/markdown-sync, but some details are still missing.

Basic functionality could look like the following:

  1. Field to enter a markdown source on GitHub. This could be a nice, proper UI, but simply accepting a custom field under a common field key convention would be enough for an MVP. Something like wporg_markdown_source would do the trick.
  2. Refresh button in the post edit screen to fetch the latest version of the content from GitHub and make updates as needed.
  3. Cron job that goes through all posts that have a custom field as registered on 1. and update as needed.
  4. Ability to specifiy a manifest file that defines the posts (and their post type) to create and their respective markdown sources.
  5. Cron job that goes through the manifest file and adds/removes/updates posts as needed.

1., 2. & 3. are also great for one-off pages/posts that should be updated from an arbitrary GitHub file, without it being tied in an automated structure. As an example, a feature project page like the one from servehappy could be set up to be updated from the corresponding GitHub repo's README.md file, or individual pages in the different team handbooks could be set up for easier collaboration.

Change History (9)

#1 @netweb
10 months ago

Agreed, the Training team have recently migrated their lesson plans to GitHub so that the 100+ lesson plans they have including assets can be under version control.

At some stage, this content will need to be sync'd back to w.org, more than likely to https://learn.wordpress.org/

#2 in reply to: ↑ description @rmccue
10 months ago

Replying to schlessera:

@rmccue has already done a lot of preliminary work for making this reusable in https://github.com/WP-API/markdown-sync, but some details are still missing.

Happy to give access to this repo if anyone wants to help maintain, or move it to a different org if we want it somewhere else

Basic functionality could look like the following:

  1. Field to enter a markdown source on GitHub. This could be a nice, proper UI, but simply accepting a custom field under a common field key convention would be enough for an MVP. Something like wporg_markdown_source would do the trick.

Right now, markdown-sync is just a library, so it has no opinions on this. In one of the themes I have using it, we've built the ability to supply the repo URL into the Customiser; I'm happy to bring this back upstream if we want to build this out into more of a plugin.

I'd rather not allow the per-page meta to be editable, as this meant to be controlled by the manifest file instead. You can implement this in another plugin atop markdown-sync though, potentially.

  1. Refresh button in the post edit screen to fetch the latest version of the content from GitHub and make updates as needed.

I think we may also have code somewhere for this (and API endpoints for the same).

This ticket was mentioned in Slack in #meta by netweb. View the logs.


6 months ago

This ticket was mentioned in Slack in #meta by netweb. View the logs.


3 months ago

This ticket was mentioned in Slack in #buddypress by netweb. View the logs.


3 months ago

This ticket was mentioned in Slack in #meta by netweb. View the logs.


3 months ago

This ticket was mentioned in Slack in #buddypress by espellcaste. View the logs.


3 weeks ago

This ticket was mentioned in Slack in #buddypress by netweb. View the logs.


3 weeks ago

This ticket was mentioned in Slack in #buddypress by boone. View the logs.


4 days ago

Note: See TracTickets for help on using tickets.