All of the content for the site uses a hybrid of Markdown and ERb—and maybe the occasional bit of HTML for edge cases. How can one possibly keep track of what’s available and which approach is the right approach in which context?

Naturally, it depends, but you can summarize it all with a relatively simple guideline:

Markdown is better than ERb which is better than HTML.

That is, Markdown works best for the bulk of the content. It’s the easiest and fastest to type while also being relatively portable to other systems without requiring changes. Markdown also ensures that quotes (both double and single) are typographically correct.

For some of the richer elements like pull quotes, figures with images or code samples, or callouts, Markdown doesn’t quite get us there. Either the resulting markup is incomplete, inflexible, or just not robust enough. In those cases, the ERb helpers ensure that you can be confident in the resulting markup.

Since the ERb helpers generate fairly involved markup, by centralizing them in helpers, any changes to the markup generated by the helpers will automatically apply across the entire site. So, for example, if it turns out that the figure elements could be made more accessible, it wouldn’t require manually updating every figure element across the entire site.

In very rare cases, there may even be reasonable justification for writing HTML directly. It should be a last resort, and it should almost always be a scenario where it’s clear that a given element is unlikely to ever be used again. Of course, if it does need to be used elsewhere, it can be extracted into a component at that time.

For some additional clarification, the following detailed guidelines may help in some situations with multiple options where it isn’t crystal clear what the best route would be:

  1. If an element can easily be rendered via Markdown, prefer the Markdown version over the markup version because it’s fewer keystrokes and less brittle. ex. * * * instead of <hr>
  2. If an element has a custom ERb helper—like visual or callout—use that because it handles all the semantic markdown. It also ensures that if there is an issue with the semantics of the markup, it can be fixed once in the helper and automatically update all instances across the entire site.
  3. If you absolutely must use embedded HTML, it’s alright for extremely rare cases where it’s not worth having a custom ERb helper because it won’t ever be used again.
  4. When embedding markup, always use double quotes rather than single quotes on element attributes for consistency.
  5. When using embedded HTML, don’t include a trailing slash in self-closing elements.11Rails—the framework behind the site—still lets some elements retain the trailing slash because it doesn’t hurt anything, but it’s not ideal. ex. <hr> instead of <hr/> or <img src=""> instead of <img src=""/>
  6. When using embedded HTML, Don’t omit optional closing tags. i.e. </li> or </body>

Some of the original content may not follow these guidelines for historical reasons. This is simply a matter of legacy content only being updated where necessary. These guidelines should be the standard for new content and whenever updating old content.