Simple Dev.to Article Improvements

• Headers
• Table of Contents
• Syntax Highlight
  • Supported Syntax Highlight Languages
  • Advanced Highlighting
• Series
• Tagging
• Conclusion

Lately I've been checking out other articles on dev.to and have noticed a few easy areas of improvement. In this article I'll show some basic things you can do to improve the overall readability and layout of your article.

Headers

Dev.to pulls from markdown headers which in turn pull from HTML headers. The HTML headers range from <h1> all the way up to <h6>. Markdown matches the number of pound symbols (#) to the respective header level:

# = <h1>
## = <h2>
### = <h3>
#### = <h4>
##### = <h5>
###### = <h6>

The lower the number the higher in the hierarchy it is. # Header would map out to <h1>header</h1> which is the top level in the hierarchy. Lower header levels also have a bigger font size. If you view the source code for any article you'll notice the title is surrounded by an <h1> tag:

            <h1 class="fs-3xl m:fs-4xl l:fs-5xl fw-bold s:fw-heavy lh-tight mb-2 medium">
              Python Deployment: WSGI
            </h1>

It's important to note that while the other headers aren't restricted by duplication you want to always have only one <h1> header. Since the title already handles <h1> or # Header for you there's no need to use that level in the article itself. As an example of how you might organize things (assuming a title "Linux Basics"):

## Login
### Terminal Access
### SSH Access
## Editors
### vim
### nano
### emacs

In fact, starting with headers as an outline and filling content in can be a good way to structure things. Sometimes it can let you switch to other parts of the article on the fly if you're struggling with one part.

Table of Contents

This leads to the next related topic: a table of contents. While not an out of the box feature there's a nice and simple solution for it. As an example, if I take one of my articles and copy everything besides the already generated ToC:

I get the following output:

{%- # TOC start (generated with https://github.com/derlin/bitdowntoc) -%}

- [CGI](#cgi)
  * [CGI Server](#cgi-server)
  * [CGI Process Spawn](#cgi-process-spawn)
  * [CGI Application](#cgi-application)
- [FastCGI](#fastcgi)
  * [Nginx Setup](#nginx-setup)
  * [FastCGI Protocol Inspection](#fastcgi-protocol-inspection)
  * [FastCGI Image Resize Server](#fastcgi-image-resize-server)
  * [Thoughts on FastCGI](#thoughts-on-fastcgi)
- [SCGI](#scgi)
  * [SCGI protocol](#scgi-protocol)
  * [SCGI Server](#scgi-server)
  * [Thoughts on SCGI](#thoughts-on-scgi)
- [uwsgi](#uwsgi)
  * [Thoughts on uwsgi protocol](#thoughts-on-uwsgi-protocol)
- [Conclusion](#conclusion)

{%- # TOC end -%}

Note that as the screenshot suggests you'll want to make sure the preset is dev.to so it matches the proper anchor generation algorithm. The cool thing about this generator is that it takes header levels into consideration and will indent ToC bullets for you depending on the level.

Syntax Highlight

Given that dev.to tends to be developer oriented, it features syntax highlighting of code blocks. Since dev.to is built on Forem, it utilizes the Rogue syntax highlighting system. A plain code block with no formatting looks like this:

import requests

post_data = {
    'test1': 'foobar',
    'test2': 'foobar',
    'test3': 'foobar'
}

r = requests.post('http://localhost:8000/', data=post_data)
print(r.content)
print(len(r.content))

By adding a label after the first three ticks of a code block, the result will be rendered with the appropriate syntax highlighting if supported:

```python
import requests

post_data = {
    'test1': 'foobar',
    'test2': 'foobar',
    'test3': 'foobar'
}

r = requests.post('http://localhost:8000/', data=post_data)
print(r.content)
print(len(r.content))
```

Becomes:

import requests

post_data = {
    'test1': 'foobar',
    'test2': 'foobar',
    'test3': 'foobar'
}

r = requests.post('http://localhost:8000/', data=post_data)
print(r.content)
print(len(r.content))

Supported Syntax Highlight Languages

To see if a particular language is supported you can use Rouge's handle tool rougify. First install a ruby interpreter. Then checkout the rouge source code and run bin/rougify list in the source code root directory:

$ git clone git clone https://github.com/rouge-ruby/rouge.git
$ cd rouge
$ bin/rougify list
== Available Lexers ==
abap: SAP - Advanced Business Application Programming

actionscript: ActionScript [aliases: as,as3]

ada: The Ada 2012 programming language

apache: configuration files for Apache web server

apex: The Apex programming language (provided by salesforce)

apiblueprint: Markdown based API description language. [aliases: apiblueprint,apib]

applescript: The AppleScript scripting language by Apple Inc. (https://developer.apple.com/library/archive/documentation/AppleScript/Conceptual/AppleScriptLangGuide/introduction/ASLR_intro.html) [aliases: applescript]

armasm: Arm assembly syntax

augeas: The Augeas programming language (augeas.net) [aliases: aug]

awk: pattern-directed scanning and processing language

batchfile: Windows Batch File [aliases: bat,batch,dosbatch,winbatch]

bbcbasic: BBC BASIC syntax
<snip>

You can either chose to identify the syntax highlight by the label before the first :, or by any of the aliases that are listed such as [aliases: aug]. For finding a particular language tag use grep or Select-String in Powershell:

$ ruby bin/rougify list | grep "dart"
dart: The Dart programming language (dart.dev)
> ruby .\bin\rougify list | Select-String -Pattern 'dart'

dart: The Dart programming language (dart.dev)

Advanced Highlighting

If you need to escape a code block, you can simply surround it with ~~~ like so:

```
Code goes here
```

The console parser also has a nifty feature that lets you syntax highlight when console prompts are present. As an example with the python interactive interpreter:

```console?prompt=>>>&lang=python
>>> print("Test")
Test
>>> import sys
>>> sys.exit()
```

Would produce:

>>> print("Test")
Test
>>> import sys
>>> sys.exit()

So it knows to ignore the >>> prompt and highlight everything after it with the language python. This is useful for basic shell commands as well:

```console?prompt=$&lang=sh
$ export FOO="BAR"
$ echo "Hello, World!"
```

Produces:

$ export FOO="BAR"
$ echo "Hello, World!"

Series

A favorite feature of mine is the series feature. Posts in a series will show up with a series table of contents at the top if there are at least two posts in a series:

To set a series, simply click on the post settings next to "Save draft":

Then you can either enter a new series name:

and click Done, or you can select an existing series:

If you want to make an existing post part of a series then simply edit the post and use the same workflow as above.

Tagging

Adding appropriate tags can help get your articles achieve more exposure. This is because as a feature users can follow certain tags to get related articles about what the tag represents. Some generic ones include:

• #webdev
• #devops
• #security
• #programming
• #tutorial

Along with a bit more specific ones

• #meta (related to dev.to)
• #aws (articles about Amazon Web Services)
• #python (articles about the python programming language)

If you're not quite sure what to pick try and see if someone else has done a related article and what tags they chose.

Conclusion

This wraps up my guide on a few items that can help with your dev.to articles. I hope it helps you get a better visual breakup and make series articles easier to navigate. Good luck and keep up the good writing!