All Collections
Course Editor Basics
Markdown standardization
Markdown standardization

A brief explanation of why we standardize the format of the Markdown powering your courses behind the scenes.

Amy Peterson avatar
Written by Amy Peterson
Updated over a week ago


As you may know, behind every DataCamp course is a set of Markdown files (stored on GitHub) containing the content. We chose this approach early on because it affords us the many benefits of using version control for tracking changes and collaborating with others. It's also a format that many people in the data science community are already familiar with, so we saw it as a way to meet instructors where they are.

But this approach has some downsides, one of which is that the information needs to be structured in a very particular way in order for our systems to parse it and turn it into the interactive courses that our learners know and love. Instead of requiring every instructor to master the idiosyncrasies of this structure, we've built an editor that abstracts away many of the details of the underlying Markdown.

When you write content in the editor, we are saving it in a very particular Markdown format behind the scenes. But some of our instructors prefer to edit the raw Markdown either on their computer or directly in GitHub's editing tools. We've built the system in such a way that makes this possible. But it's likely that the Markdown someone writes by hand doesn't perfectly align with the format we need. Enter Markdown standardization.

Markdown standardization

If you open a course in the editor that doesn't follow our standard Markdown format, you'll be prompted to either have us reformat it automatically or remain in view-only mode so the content can't be edited. You'll see a popup that looks something like this:

If you select View Only, no changes will be made to the content, but you won't be able to do any editing. The next time you open the editor or refresh the page, you'll see the same prompt as long as the Markdown hasn't yet been reformatted.

When select Reformat Content, we'll make a single, automated commit to GitHub behind the scenes to reformat the Markdown in a way that aligns with our standard format. This way, when you move on and start saving other changes to the content, those future saves will appear in separate commits from the one used to standardize the formatting. This, in turn, makes it easier for you to separate the changes you really care about from the ones we make to keep everything tidy.

Will I have to do this every time?

Nope! You should only encounter this when changes have been made directly to the raw Markdown. As long as you're using the editor, we'll automatically keep things in order for you. 

If you have any questions, give us a holler. We're here to help!

Did this answer your question?