Prepare and cross-post Bryntum articles
We prepare Bryntum drafts in markdown, but later prepare different formats of the same article. We should always treat the markdown version in GitHub as the canonical version, so any changes made later to other versions should always be backported to the markdown version.
Overview of formats and versions
- The markdown version in GitHub - https://github.com/ritza-co/bryntum
- A wordpress version for their blog. This we prepare as a draft on their staging server, and they publish it to live from there
- A medium version for their Medium.com account
- A dev.to version for the Dev.to account
- [for migration guides] - a markdown version in their docs repository. Their docs are in a mono-repo with their source code which they are very protective over, so we have a bryntum-docs repository that mirrors the same structure as their main repo, but only including the docs we are working on.
Overview of process
- Once an article has gone thorugh drafting, QA, and editing, it can be uploaded to wordpress. Create a draft (guide below) on wordpress and add a header image.
- Copy the HTML version of the wordpress version and craete a PR with this back to our main Bryntum GitHub repository. This is because WordPress can be janky and once all the finicky formatting is done we don't want to lose that work
- Once the article has been live on their WordPress blog for a couple of weeks, create a Medium.com and Dev.to version [guide to be created].
Steps for creating a WordPress draft
The article should be copied from the GitHub by clicking and dragging over the article, rather than clicking on the copy
button. This is because the copy
button does not copy the text in markdown format, which we will need later on in the crossposting.
Next the article can be pasted into the Wordpress visual editor.
Here the editor will automatically format the markdown. Not all of the article will be formatted correctly and some adjustments may need to be made.
Code block syntax highlighting
In the WP visual editor
, run through the article and check the block type of all of the code snippets. Convert all code snippets to the code
block type.
Swicth to the Wordpress code editor
and run through all of the <!-- wp:code -->
code blocks. Add the following class to both the <pre>
and <code>
tags of these blocks:
class="language-(language-type-here)"
Ensure that the appropriate language is added to that class to ensure the code block has the correct syntax highlighting.
This can be made easier by copying the html
version of the article from Wordpress, pasting into a text editor and using the find functionality (cmd/ctrl+f
) to locate all of the <!-- wp:code -->
blocks.
Each code block should be wrapped in a tag that looks something like this:
<!-- wp:code -->
<pre
class="language-javascript wp-block-code"
><code class="language-javascript">CODE-GOES-HERE</code></pre>
<!-- /wp:code -->
For HTML syntax use markup
as the language in the class:
<!-- wp:code -->
<pre
class="language-javascript wp-block-code"
><code class="language-javascript">CODE-GOES-HERE</code></pre>
<!-- /wp:code -->
Images, gifs, and videos
Go through the Wordpress block editor and delete the image blocks one by one and replace with the appropriate image for that section of the article.
All video or gif files must be converted to webm
format. You can use this website to do the converting. The webm
format is preferred because of its better quality.
Upload webm
files using the video
type of code block in the visual editor. If the video
option is not listed in the mini drop down box you can search for it.
Making the header image
To make the header image take the screenshot of the final software demo, or if the article is a comparison between two demos take the screenshots of both software demos, and place these images inside the Bryntum frame found in the Figma project.
Attach the header image in the cover image section.
Final checks
Once you have completed these steps, run through the article to make sure all the formatting has been copied over correctly. Check the headings, lists, bullet-points, images, etc.
Changing the Ritza GitHub links
Any links to a Ritza GitHub repo in the article should be sent to Bryntum to fork, that Bryntum repository should replace any Ritza repository links in the article. Please check the article and let Bryntum know if they need to fork all branches of the repository.
Pick an article category
Make sure to pick a category for the article from the Wordpress sidebar. The category should match the category of similar articles previously posted, which can be checked inside Wordpress.
Save HTML version of article
Once the article is complete, copy the html
text from the Wordpress code editor
, create a file in the Ritza GitHub repository alongside the original article, and paste the text there. We keep this html
version in case something corrupts the Wordpress version.