Example Blog Article

You can see this blog example as rendered in the pre-publication environment at https://rearc-website-develop.noop.app/blog/example.

h2 lorem ipsum

h3 lorem ipsum

h4 lorem ipsum

h5 lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc luctus sed est in semper. Etiam iaculis finibus quam id fermentum.

italics text

bold text

HTTP anchor example

• unordered list
• unordered list
• unordered list

1. ordered list
2. ordered list
3. ordered list

example code block

This is an example of inline code and can be embedded in any block of markdown text.

This is an example of quoted text or a "callout" emphasizing some important information. Currently, the display of inline code (code) in callouts is not readable (it displays as white text on a light pink background). This is also true for HTML code blocks like this one, as well as quoted code blocks like the following:

Copy

example quoted code block

Images

Basic support for images and inset images are provided using Markdown image links or the HTML <Image> tag. Markdown links are preferred unless you need specific formatting options like image size or location. Whichever you use, always provide alt-text briefly describing the image for screen readers.

Embed an image and its screenreader "alt" text with Markdown like this:

![Laptop computer being used to write code](/cms/blog/example/laptop.webp)

An HTML format image link may be displayed between paragraphs, like so:

<Image src="/cms/blog/example/laptop.webp"
 alt="Laptop computer being used to write code" />

NOTE: Make sure that the "<Image>" tag starts on the first column of your MDX code. See the example.mdx source file for this post for details.

Floating the content to the right is done with the float="right" attribute:

<Image src="/cms/blog/example/laptop.webp" float="right"
 alt="Laptop computer being used to write code" />

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus lacinia dapibus orci, sed sodales neque finibus a. Vivamus vehicula pulvinar orci a tristique. Morbi nisi ligula, condimentum quis odio id, malesuada malesuada risus. Mauris a egestas sapien. Cras eget urna viverra orci posuere condimentum.

Floating the content to the left is done with the float="left" attribute:

<Image src="/cms/blog/example/laptop.webp" float="left"
 alt="Laptop computer being used to write code" />

Integer vitae nulla eros. Duis iaculis elit quis orci lobortis, nec vehicula dui feugiat. Mauris luctus purus ac elit mattis, in faucibus sapien interdum. Donec mi diam, consectetur id erat vitae, malesuada bibendum justo. Morbi pulvinar rutrum tincidunt. Integer rhoncus libero ornare feugiat condimentum.

Citations

Bibliography style citations are supported through use of the <Citation> tag.

Also make sure that the <Citation> tag starts on the first column of your MDX code. See the sourcecode of this file for more information.

<Citation id="xkcd">
Munroe, R. (n.d.). xkcd: Code Lifespan. Retrieved October 1, 2024, from
https://xkcd.com/2730/
</Citation>

This will create an id-tagged element suitable for use in a hyperlink. See the referenced XKCD citation for more information (Munroe, 2024).

Plotly support

You can embed dynamically generated Plotly graphs using <Plot>. The following is an example using inline data with style attributes height and width applied to the element style. Make sure that the <Plot> tag starts in the first column of your MDX code.

<Plot
  data='[
    {
      "x": [1, 2, 3],
      "y": [2, 6, 3],
      "type": "scatter",
      "mode": "lines+markers",
      "marker": {"color": "red"}
    },
    {"type": "bar", "x": [1, 2, 3], "y": [2, 5, 3]}
  ]'
  height="240px"
  width="320px"
/>

With large quantities of data it's preferable to use the src attribute instead of data, fetching content from the server via the CMS API. The data file must be pure JSON with no comments, and stored under public/cms. Pre-commit checks verify that the JSON file parses correctly.

 <Plot src="blog/example/bar_plots.json" height="800px">

There are some "gotchas" to beware of with Plotly graphs. Blog content is rendered by markdown-to-jsx, not an MDX/JSX compiler, and JavaScript inside braces {} is not executed – it's passed through as literal, unparsed text. The markdown-to-jsx conversion also treats any attribute value starting with { and ending with } as a JSX expression and strips those outer braces before trying to interpret it — even a quoted string as in layout='{"width":320}'. This prevents any use of layout or other attributes that take a JSON object.

The data attribute is safe to inline as a single-quoted, valid JSON array string (it starts with [, so the brace-stripping above doesn't apply). See the example.mdx source file for this post for details.

Don't do this — layout here loses its outer braces and fails to parse:

<Plot
  data='[
    {
      "x": [1, 2, 3],
      "y": [2, 6, 3],
      "type": "scatter",
      "mode": "lines+markers",
      "marker": {"color": "red"}
    },
    {"type": "bar", "x": [1, 2, 3], "y": [2, 5, 3]}
  ]'
  layout='{
    "width": 320, "height": 240, "title": "A Fancy Plot"
  }'
/>

References

Munroe, R. (n.d.). xkcd: Code Lifespan. Retrieved October 1, 2024, from https://xkcd.com/2730/