WordPress.org

Making WordPress.org

Opened 5 months ago

Last modified 10 days ago

#5247 accepted enhancement

Import Hosting Handbook Markdown from Github

Reported by: mikeschroder Owned by: coffee2code
Milestone: Priority: normal
Component: Handbooks Keywords: has-patch
Cc:

Description

In #5240, a hosting handbook repo was created: https://github.com/wordpress/hosting-handbook

Now, I'm looking to figure out the best way to set up automated import of the Markdown there.

I noticed that both WP-CLI and Gutenberg are set up to auto-import, with slightly different ways of using the library plugin.

I've tested importing on a VVV meta repo, but am having trouble testing the styles.

Attached is a first draft of the WP-CLI handbook plugin ported to the hosting handbook. Not sure if it's better to go this route, or duplicate less code somehow.

Attachments (1)

hosting-handbook-importer.diff (18.3 KB) - added by mikeschroder 5 months ago.
First pass -- Hosting Handbook importer plugin.

Download all attachments as: .zip

Change History (17)

@mikeschroder
5 months ago

First pass -- Hosting Handbook importer plugin.

This ticket was mentioned in Slack in #hosting-community by mike. View the logs.


5 months ago

#2 follow-up: @mikeschroder
5 months ago

Ah, I should note, I did notice that assets/images don't seem to get added to the WP media library on import.

I'm not sure if I did something wrong there, if they should be transformed, or if the intended behavior is to link to the assets elsewhere.

#3 in reply to: ↑ 2 ; follow-up: @dd32
5 months ago

Replying to mikeschroder:

Ah, I should note, I did notice that assets/images don't seem to get added to the WP media library on import.

I don't think there's any handling for images, and I'm not sure any of the existing handbooks that use GitHub have them.

#4 in reply to: ↑ 3 @mikeschroder
5 months ago

Replying to dd32:

I don't think there's any handling for images, and I'm not sure any of the existing handbooks that use GitHub have them.

Thanks; I wondered if maybe that was why Gutenberg's docs seem to use Cloudup for images. The hosting handbook only has two images at the moment, so it wouldn't be hard to move them wherever they need to be, then document how to add future images.

#5 follow-up: @dd32
5 months ago

so it wouldn't be hard to move them wherever they need to be, then document how to add future images.

I would recommend just uploading them to the media library manually, and inserting the wordpress.org link into the markdown :)
If that becomes a problem long-term, someone can offer to add sideloading functionality to the handbook plugins.

#6 in reply to: ↑ 5 @mikeschroder
5 months ago

Replying to dd32:

I would recommend just uploading them to the media library manually, and inserting the wordpress.org link into the markdown :)
If that becomes a problem long-term, someone can offer to add sideloading functionality to the handbook plugins.

Thanks! Sounds like a plan.

These are already uploaded, and the links have been changed + docs added.

This ticket was mentioned in Slack in #hosting-community by mike. View the logs.


5 months ago

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


5 months ago

#9 follow-up: @dd32
5 months ago

@coffee2code Is there a new importer that doesn't need to be copy-pasted every time? I think you're far more familiar than me with the handbooks..

#10 in reply to: ↑ 9 ; follow-up: @coffee2code
5 months ago

Replying to dd32:

@coffee2code Is there a new importer that doesn't need to be copy-pasted every time? I think you're far more familiar than me with the handbooks..

Unfortunately, no. I believe heretofore, no other site other than DevHub had use for a GitHub docs importer until now. The Gutenberg demo site did have its own version introduced a couple months after DevHub introduced a specialized one for the REST API docs. But that was decommissioned early last year as the DevHub docs importer was abstracted into a base class to accommodate multiple imported docs (REST API, Coding Standards, and Block Editor). At which point the Gutenberg site docs importer was itself decommissioned.

The base docs importer code is only minimally DevHub-branded and specific and could probably be made general-purpose and integrated into the Handbooks plugin. I'll give it a go.

#11 in reply to: ↑ 10 @mikeschroder
4 months ago

Replying to coffee2code:

Unfortunately, no. I believe heretofore, no other site other than DevHub had use for a GitHub docs importer until now.

Thanks so much for looking into this! It would be great to have something more abstracted/general.

I'm pretty sure you're aware, but just to be sure, it looks like the WP-CLI Handbook / plugin also uses a Markdown importer, and that's the one I initially based off of.

#12 follow-up: @coffee2code
4 months ago

  • Owner set to coffee2code
  • Status changed from new to accepted
  • Type changed from defect to enhancement

@mikeschroder: Just to confirm, has all of the data in the existing handbook pages (on make/hosting) been incorporated into the GH version? I don't want to inadvertently overwrite anything that'll be missed.

#13 in reply to: ↑ 12 @mikeschroder
4 months ago

Replying to coffee2code:

@mikeschroder: Just to confirm, has all of the data in the existing handbook pages (on make/hosting) been incorporated into the GH version? I don't want to inadvertently overwrite anything that'll be missed.

Yes! It was all ported to the Github version, and it has been worked on there since.

#14 @mikeschroder
2 months ago

Hey, just thought I'd check in here -- is there anything you need / any way I can help out?

This ticket was mentioned in Slack in #hosting-community by mike. View the logs.


10 days ago

#16 @mikeschroder
10 days ago

@coffee2code Thought I'd check in on this again. There have been some parts waiting to be updated/published since this request was created here.

Do you know what the timeframe looks like? Wondering if we should update them manually, or in some other fashion.

Also happy to help / put together another pass if it is helpful, but wasn't sure where you were on the process.

Thanks again!

Note: See TracTickets for help on using tickets.