Whether you're a first-time author or a TDS veteran, welcome to our formatting guide!
As of August 2026, we launched our bespoke author platform to replace the WordPress site we'd previously used. You can expect a much easier, more intuitive, and more streamlined drafting experience here, but in case you'd like some guidance on how to upload your work to TDS, you're in the right place.
Table of contents
- Essential Elements
- Adding the contents of your article
- Text
- Headings
- Lists
- Blockquote
- Separator
- Table
- Code and GitHub Gists
- Math notations
- Images
- Video options
- Social embeds
- Link embeds
- Table of Contents
- How can I ask for help with my draft?
Essential Elements
Whenever you'd like to start a new article draft, look for the + New Article button on the top-right corner of the page. You'll immediately see a pop-up modal inviting you to add key details about your work, like the title, subtitle, main category, and tags. If you're not sure about some of these, that's fine — the only required field at this stage is the article's title. And you can always edit these details later if you'd like.
Once you click on the Create Article button you'll reach the editor screen. The other required element to think about now is the featured image. Look to the sidebar to find the options for choosing or creating one.
If you've created a custom image for your article, fantastic — click on Upload image and choose it from your computer. If you've already uploaded your image to to your media library, or decided to repurpose an image from an older article, pick Choose from library and select the image you want.
You also have the option to generate your image using AI directly from your draft using — you guessed it — the Generate with AI button. Click on it and a new modal will appear.
Just type in your prompt — feel free to be as descriptive and specific as you want — and click Generate. After a few seconds you'll see several options to choose from.
If you ever need some additional guidance on choosing a featured image, or want to refresh your memory around our guidelines, here's a FAQ that covers the topic.
Adding the contents of your article
With the essential elements out of the way, it's time to actually upload your article. Our streamlined UI will get your draft ready for review with minimal hassle.
To add regular text, simply start typing. To add any other kind of content or media, always start with the / key. A block menu will pop up, showing all the available content types you can add.
Use the up and down arroes to scroll through the list, choose the block you want at that point in your article, and go from there. Let's take a closer look at your options.
Text
Self-explanatory! Just type in or paste your written content. Whenever you start a new paragraph, it's set to text by default, so you don't actually need to use the / key (unless you really want to).
To add special styling to any part of your text, highlight the relevant portion and you'll see a menu pop up:
You can choose between bold, italic, underline, strikethrough, abd inline code. This is also where you'll find the link button and alignmnet options.
The text box symbol is where you should go if you want to leave a comment for our editors. Click on it, write your comment, tag someone specific from our team if you'd like (using the @ symbol), and click on Comment to submit it.
Tip: to find all your comments in one neat space, look to your sidebar, and click on the Threads tab.
Headings
Creating a clear structural hierarchy within your article helps both readers and search engines navigate your content. Add a new heading whenever you start a new section, and choose the right one depending on its position within your article.
When you type /heading you'll see six levels available. Always start new sections with H2, and go down the hierarchy from there: for example, Section 1 in H2, Section 1.1 in H3, Section 1.11 in H4, etc. Please don't use H1 headings in the body of the article.
Lists
You have the option to create both bulleted and numbered lists, depending on your needs — just choose the right block from the list and you're good to go.
Tip: use the tab button to nest a secondary list within your primary list.
Blockquote
Choose the blockquote block to highlight specific points or ideas, or when you're quoting longer passages from external sources.
Using blockquotes sparingly can be very effective, but don’t overdo it — just like bold or italicized text, they can quickly become distracting.
Separator
Sometimes, a heading might feel insufficient for creating a visual break between or within sections.
In those cases, use the Separator block — just make sure you select the Dotted style, which is the one we chose as our default on TDS. (If for some reason you absolutely need to use a different style of separator, that's probably ok. Just leave us a comment explaining your choice.)
Table
Tables are great for comparing benchmark results, product features, and more. The Table block makes creating sleek tables very easy.
The + buttons below and to the right of the table will add rows and columns, respectively. The other settings in the pop-up menu allow you to toggle the header row and column, align the table vertically, delete rows and columns, and delete the table entirely.
Code and GitHub Gists
Many TDS articles include code — sometimes lots of code. The text block we covered above gives you access to inline code styling, however that's not a practical solution for more than, say, a short snippet. You have two great options to choose from:
Code block
Choose a code block when you'd like to input code directly into the draft and choose a language-specific syntax highlighting for it. Just paste your code into the block — then, either keep it in Auto mode and our site will choose the most appropriate highlights for it, or scroll down the list of available programming languages and choose the relevant one.
If the block only contains outputs, natural-language prompts, etc., rather than working code, just pick Markdown, which will keep it in plaintext.
GitHub Gists
You also have the option of embedding GitHub Gists directly into your draft, which can be useful if you're bringing your work over from a repo.
All you need to do is paste the URL of your gist (make sure it starts with gist.github.com) and click on Embed — it will magically appear in your draft and in the final article.
Math notations
One of the biggest upgrades of our bespoke editor is how easy it is to add equations, formulas, and any other math symbol-heavy content. Here, too, you have two options to choose from.
Inline Math
Go with the Inline Math block when you need to insert mathematical symbols or notations in the midst of your running text — just type it into the input box, check the preview below it to make sure everything looks good, click Save, and you're done.
Block Math
For longer and more complex mathy stuff, opt for Block Math — this is where you can truly work your LaTeX magic. Once again, use the preview below the input box to make sure all the sigmas and deltas are in the right spot.
Images
For charts, plots, screenshots, animations, and so on, use the Image block. You have several options here: uploading, using an image already in your media library, adding via URL, or generating one using our built-in AI tool. Go wild! (Ok, not too wild, please.)
Once you're image is in, you can click on it and a settings popup will appear. This is where you can control its dimensions and alignment, add an alt and a title, and delete it if you decided not to use it.
The most important setting here is the caption — the second symbol from the left. This is where we ask all authors to add sourcing and licensing information for all their images, including those they generated with AI and/or created themselves.
Tip: if your article contains numerous images, and you created all or most of them, you can avoid adding an annoying number of captions by adding a note along the lines of "All images, unless otherwise noted, are by the author." Then you only have to add captions to the ones you've sourced from third parties.
Video options
Looking to add a a live demo, a lecture you gave, or the song your audio ML project is referring to? Easy — just embed it using either the YouTube, Vimeo, or DailyMotion embed blocks. They all work the same way: choose the right block, paste the URL of the video you'd like to add, and click Embed. The result is a natively embedded, controllable video player:
The best way to include content from social media in your articles is embedding them — the formatting is already optimized for our site, and you avoid running into thorny copyright issues, since you're essentially re-sharing the original post. Beyond the video embeds we mentioned in the previous subsection, you can also embed tweets and Reddit posts following the exact same process: choose the block, paste the URL, click Embed, and presto!
Link embeds
Use the Link embed block to create styled embedded links to other URLs. Choose the block, paste the link to the page in question, and click Embed.
Table of Contents
For a final bit of magic, you can automatically generate a clickable table of contents of your article by adding the... Table of Contents block! It works by collecting all your headings and subheadings into a TOC format, so giving your thoughts to the internal structure of your article will pay off here.
To create it, just add the Table of Contents block wherever you'd like it to appear — for example, after a quick intro (and, ideally, before your first heading).
Tip: TOCs are optional; they usually work best in longer pieces and deep dives, and can feel a bit superfluous in a short, code-heavy article, for example.
How can I ask for help with my draft?
If this guide hasn't addressed the question you had or an issue you ran into, no worries — you can reach out to use directly from your draft. Just highlight any word(s), click on the comment symbol, and tag one of our team members with the @ symbol. (If it's a longer question and you prefer to email us, you can — find us at publication@towardsdatascience.com.)
Instagram Engineering
Shopify Engineering