Skip to content
Search

DEV Community

Editor Guide 🤓

Things to Know

  • We use a markdown editor that uses Jekyll front matter.
  • Most of the time, you can write inline HTML directly into your posts.
  • We support native Liquid tags and created some fun custom ones, too! Trying embedding a Tweet or GitHub issue in your post, using the complete URL: {% embed https://... %}.
  • Links to unpublished posts are shareable for feedback/review.
  • When you're ready to publish, set the published variable to true.

We have two editor versions. If you'd prefer to edit title and tags etc. as separate fields, switch to the "rich + markdown" option in Settings → Customization. Otherwise, continue:

Custom variables set for each post, located between the triple-dashed lines in your editor Here is a list of possibilities:

  • title: the title of your article
  • published: boolean that determines whether or not your article is published
  • description: description area in Twitter cards and open graph cards
  • tags: max of four tags, needs to be comma-separated
  • canonical_url: link for the canonical version of the content
  • cover_image: cover image for post, accepts a URL.
    The best size is 1000 x 420.
  • series: post series name.

Below are some examples of commonly used markdown syntax. If you want to dive deeper, check out this cheat sheet.

Italics: *asterisks* or _underscores_

Bold: **double asterisks** or __double underscores__

I'm an inline link: [I'm an inline link](put-link-here)

Anchored links (For things like a Table of Contents)

      ## Table Of Contents
        * [Chapter 1](#chapter-1)
        * [Chapter 2](#chapter-2)

      ### Chapter 1 <a name="chapter-1"></a>

When adding GIFs to posts and comments, please note that there is a limit of 200 megapixels per frame/page. example image, with sloan 

![Image description](put-link-to-image-here)
example image, with sloan
You can even add a caption using the HTML figcaption tag!

Add a heading to your post with this syntax:

# One '#' for a h1 heading
## Two '#'s for a h2 heading
...
###### Six '#'s for a h6 heading

Add some hidden notes/comments to your article with this syntax:

<!-- This won't show up in the content! -->

People access online content in all kinds of different ways, and there are a few things you can do to make your posts more easily understood by a broad range of users. You can find out more about web accessibility at W3C's Introduction to Web Accessibility, but there are two main ways you can make your posts more accessible: providing alternative descriptions of any images you use, and adding appropriate headings.

Providing alternative descriptions for images

Some users might not be able to see or easily process images that you use in your posts. Providing an alternative description for an image helps make sure that everyone can understand your post, whether they can see the image or not.

When you upload an image in the editor, you will see the following text to copy and paste into your post:

![Image description](/file-path/my-image.png)

Replace the "Image description" in square brackets with a description of your image - for example:

![A pie chart showing 40% responded "Yes", 50% responded "No" and 10% responded "Not sure"](/file-path/my-image.png)

By doing this, if someone reads your post using an assistive device like a screen reader (which turns written content into spoken audio) they will hear the description you entered.

Headings provide an outline of your post to readers, including people who can't see the screen well. Many assistive technologies (like screen readers) allow users to skip directly to a particular heading, helping them find and understand the content of your post with ease.

Headings can be added in levels 1 - 6. Avoid using a level one heading (i.e., '# Heading text'). When you create a post, your post title automatically becomes a level one heading and serves a special role on the page, much like the headline of a newspaper article. Similar to how a newspaper article only has one headline, it can be confusing if multiple level one headings exist on a page.

In your post content, start with level two headings for each section (e.g. '## Section heading text'), and increase the heading level by one when you'd like to add a sub-section, for example:

## Fun facts about sloths

### Speed

Sloths move at a maximum speed of 0.27 km/h!

We support native Liquid tags in our editor, but have created our own custom tags as well. A list of supported custom embeds appears below. To create a custom embed, use the complete URL:
{% embed https://... %}

  • DEV Community Comment
  • DEV Community Link
  • DEV Community Link
  • DEV Community Listing
  • DEV Community Organization
  • DEV Community Podcast Episode
  • DEV Community Tag
  • DEV Community User Profile
  • asciinema
  • CodePen
  • CodeSandbox
  • DotNetFiddle
  • GitHub Gist, Issue or Repository
  • Glitch
  • Instagram
  • JSFiddle
  • JSitor
  • Loom
  • Kotlin
  • Medium
  • Next Tech
  • Reddit
  • Replit
  • Slideshare
  • Speaker Deck
  • SoundCloud
  • Spotify
  • StackBlitz
  • Stackery
  • Stack Exchange or Stack Overflow
  • Twitch
  • Twitter
  • Twitter timeline
  • Wikipedia
  • Vimeo
  • YouTube

Call To Action (CTA)

{% cta link %} description {% endcta %}

Provide a link that a user will be redirected to. The description will contain the label/description for the call to action.

Details

You can embed a details HTML element by using details, spoiler, or collapsible. The summary will be what the dropdown title displays. The content will be the text hidden behind the dropdown. This is great for when you want to hide text (i.e. answers to questions) behind a user action/intent (i.e. a click).

  {% details summary %} content {% enddetails %}
  {% spoiler summary %} content {% endspoiler %}
  {% collapsible summary %} content {% endcollapsible %}

KaTex

Place your mathematical expression within a KaTeX liquid block, as follows:

{% katex %}
 c = \pm\sqrt{a^2 + b^2}
{% endkatex %}

To render KaTeX inline add the "inline" option:

{% katex inline %}
 c = \pm\sqrt{a^2 + b^2}
{% endkatex %}

RunKit

Put executable code within a runkit liquid block, as follows:

{% runkit
// hidden setup JavaScript code goes in this preamble area
const hiddenVar = 42
%}
// visible, reader-editable JavaScript code goes here
console.log(hiddenVar)
{% endrunkit %}

To parse Liquid tags as code, simply wrap it with a single backtick or triple backticks.

`{% mytag %}{{ site.SOMETHING }}{% endmytag %}`

One specific edge case is with using the raw tag. To properly escape it, use this format: 

`{% raw %}{{site.SOMETHING }} {% ``endraw`` %}`

Lists are written just like any other Markdown editor. If you're adding an image in between numbered list, though, be sure to tab the image, otherwise it'll restart the number of the list. Here's an example of what to do: example image of writing lists with images in Markdown

Here's the Markdown cheatsheet again for reference.

Happy posting! 📝