Skip to content

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.

WP 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.

Switch 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-markup wp-block-code"
><code class="language-markup">CODE-GOES-HERE</code></pre>
<!-- /wp:code -->

Images, gifs, and videos

All images should be optimized using tinyPNG to reduce the file size while preserving its quality.

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.

Figma tips for adding and resizing images:

Add a new image by creating a shape first. Select the rectangle tool and drag out the shape on the frame.

Once you have the shape, add the image by selecting the "Place image/video..." option which will open your file explorer. Select the image you want to use and add it to the shape by clicking on the shape.

Crop image layers by double clicking on it and selecting the "Crop" option of the dropdown menu.

Use the blue handles to selection the portion of the image that you want to crop and press enter.

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.

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.