We all know what makes both authors and editors happy: a smooth, streamlined publication process where the path from draft to published article is quick and painless.
We also know that many of our contributors—old-timers and new ones alike—might not have a lot of experience working with WordPress, the software powering our independent publication, and specifically with its block editor. We put together this guide to offer you concrete pointers, and to address some of the common questions authors have asked us. You can read this post from top to bottom (especially if you have zero block-editor experience), or jump ahead to the sections that are relevant to your current needs.
What is the block editor?
The publishing tool at the core of our website is the block editor. You can find ample resources on its various components and features on the WordPress documentation site; if you’ve never used it before, a good place to start is this page, which explains the basic actions you can take when using the editor and offers a clear legend for the many buttons and symbols you see around (and within) your content.
Keep in mind that if you’ve already used the block editor in the past as a site admin or editor, the view you’ll see as a TDS author is going to be a bit different. We wanted to provide you with a focused drafting environment with minimal distractions, so only the tools and options you’ll need to format your articles will be visible.
How do I start a new draft?
Each time you land in your author dashboard on our Contributor Portal, you can start a new draft by clicking on Posts → Add New Post:
If you already have a few drafts on our site in various states of completion, clicking on this link will take you directly to a list of your articles; just choose the one you’d like to work on.
What are the essential elements that all TDS articles must have?
As you probably know by now, TDS is very flexible in terms of article formats, perspectives, and writing tone. But every article must have the following components in place before we can publish it.
Title
An engaging, descriptive, concise title is essential. Type it into the top text field above your article’s content, and you’re all set:
Bonus points: make sure your title is written in title case — for example, “My Title Is Irresistible and Succinct, but Not Clickbait-y,” rather than “My title is irresistible and succinct, but not clickbait-y.” (The latter is sentence case, which we reserve for your subtitle.)
Subtitle
Speaking of subtitles: you need one! Brevity is great — the idea is to add just a bit more context to your title and improve the odds that potential readers decide to click on your article.
In the block editor, the subtitle is called a subheading, and you add it directly into — you guessed it — the subheading field, which you’ll find in the post settings sidebar, just to the right of the article’s content:
If you’re feeling a little bit more adventurous, copy and paste your subtitle (sorry, subheading) into the Post Excerpt field, which is near the top of the very same post settings sidebar. (If you’re not feeling that adventurous, no worries — our editors will take care of that one for you.)
Featured image
Every article needs one! Whether you find yours online (copyright-free, of course), create it yourself, or generate one with an AI tool, it’s the most important visual element in your article, so it’s worth spending a few minutes on this choice. (Here are some ideas and guidance if you’re not sure how to go about it.)
Once you’re ready, upload your image to its designated Featured image slot, not into the body of your article. Just click on the Set featured image button in the post settings sidebar.
To bring true tears of joy to your editors’ eyes, once the image is uploaded, don’t forget to add a caption with the necessary sourcing details:
Tags and Categories
Feel free to add one category and up to five tags to your articles. While this is an essential element, it’s one we’re happy to take care of for you — so if you’re not sure which ones to choose, just leave these to us.
Note: we truly believe in the top-notch quality of all the articles we publish on TDS, but we ask that you don’t add our featured tags (like Deep Dives or Editors’ Pick) yourself. Our team considers every article, and we then add these tags on our end to a handful of articles each day.
The most common blocks you’ll use (and how to use them)
Paragraph
This is where the text of your article goes — which is why the Paragraph block is likely going to be the one you use most frequently. Place your cursor anywhere in the paragraph to make the options menu visible, and highlight any words to which you’d like to add specific styles like bold, italic, and inline code, among others.
Heading
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.
H1 headings should be reserved for your article’s title, so don’t add any more of those in the body of your post. H2 headings are for new sections, and if your larger sections contain shorter subsections, you can use H3 or H4 headings as needed.
Image
Use the Image block to add most visual media to your article —charts, screenshots, animations, etc. The most important thing to remember is that you shouldn’t copy-and-paste images into the block editor — you need to upload every media file directly to our site’s Media Library.
Once uploaded, however, you can re-use the same image multiple times within the same article or across several articles.
Don’t forget to add an image caption to your images — that’s where you provide readers (and your TDS editors) with the necessary information about your image source and licensing status.
If you could use a quick refresher on our image guidelines, we’ve got you covered.
Quote
Quote blocks are a visual way for highlighting specific points or ideas, or for quoting longer passages from external sources.
Using them sparingly can be very effective, but don’t overdo it — just like bold or italicized text, Quote blocks can quickly become distracting.
List
Whether for your…
- table of contents,
- key takeaways,
- or any other element in your article that can benefit from a neat, bulleted arrangement…
…the List block should be your go-to. The block editor will automatically detect if you’re creating numbered or unordered lists once you type in the first item.
To add a nested list within your list, just start a new item and click your tab button.
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:
Prismatic (for code blocks)
Many (many!) of our articles feature code, and lots of it, so we wanted to make sure it looks neat, clear, and professional. To do that, we’ve enabled the Prismatic block, which should be your default choice for embedding longer code blocks into your article. (One main exception: if you decide to use GitHub Gists instead, which we also welcome.)
Feel free to type in your code or to copy-and-paste it from an IDE. The one crucial thing you need to remember, however, is to choose the block’s programming language — otherwise, your code will not display properly on the TDS frontend. Fortunately, selecting the right language is a breeze, and you can do it straight from your block settings sidebar:
With dozens of programming languages to choose from, you’re almost certain to find the one you need. On the off chance you don’t, select one that’s close enough, syntax-wise, to the exotic, up-and-coming language you’re coding in. (If you ever just want to present plaintext within a code block, your best bet is to go with HTML.)
Shortcode (for LaTeX notations)
If your article includes a lot of formulas (or formulae, if you insist), equations, and other math notations, you can ensure they look great on TDS by inserting your LaTeX markup into a Shortcode block. There are a couple of different approaches for doing that, and we strongly recommend reading the documentation by MathJax-LaTeX, which is the WordPress plugin powering LaTeX on our site.
If your needs aren’t as elaborate, you can also…
- Directly add a smattering of ≠, π, or ∑ (to name a few examples) using handy keyboard shortcuts.
- Create your fancy equations on the external tool of your choice, and take a screenshot — which you’ll then upload into an Image block.
Table
Great for comparing experiment results, product features, and more, the Table block makes creating sleek tables very easy — just decide how many columns and rows you need and you’re pretty much ready to go.
You can further customize your table using the block settings sidebar (to choose fixed-width cells, add a header section, etc.).
Embeds
We’ve enabled several frequently used embed types for authors, allowing you to seamlessly integrate content from other platforms into your articles.
GitHub Gists
Sharing your code via Gists is common among data and ML professionals, and this block makes it possible to extend this practice into your TDS articles. It requires two simple steps:
- On GitHub, copy the embed link from your GitHub Gist:
2. Add a GitHub Gist Embed block to your article, and, in the block settings sidebar, paste the embed link. You should immediately see a preview of your Gist.
You can add as many Gists as you’d like, and their formatting will stay the same on our site.
Media embeds
If you’d like to embed tweets, YouTube videos, and other embeddable media from external platforms, click the + symbol in the block editor, type embed, and you’ll see the various options at your disposal.
Then, paste in the URL of the media you’d like to embed into the block, and let the editor do the rest. Note that for some platforms, you might need a special embed link.
If you’d like to embed other media but are not sure if it’s possible or how to go about it, just reach out — we’ll do our best to find a solution for you.
How can I ask for help with my draft?
We’re glad you asked! If you ever run into any issue during the review process, while drafting your article, or even after your post is published, you can always reach out directly from the block editor. Just highlight any word, click on the new comment symbol, and type in your question, note, or concern.
Two important things to remember:
- For the fastest response time, tag one of our team members when you enter your comment — typing the @ symbol will show you a list of the editors you can ping.
- Always save your draft after you post a comment. This ensures your comment doesn’t disappear into thin air if you make changes to your draft, and sends a notification to the editor you pinged.
My draft is good to go! What’s next?
Congrats! You’re almost done. Here are two things you should do before submitting your article for review — and one thing you absolutely have to do for us to actually review it.
- Giving your article a final proofread is never a bad idea (we can’t overstate the benefits of sending us a clean first draft).
- We also recommend you check out your draft preview — it’s fun to see how your article would look once it’s published, and it also offers you a chance to double-check everything is formatted and displayed as you’d intended. To preview your article, click on the laptop symbol (we think it’s a laptop symbol?) near the top of the editor screen.
- Finally, please don’t forget to submit your article for review — which you can do by clicking on the (drumroll, please) Submit for Review button at the top-right corner of the block editor.
Once you click on the button, your article enters our review queue; you can still make changes to it, but it’s best to keep these to a minimum once you receive a notification that it’s in review.
If you still have any questions or run into any issues while drafting and formatting your article, feel to reach out via email or by pinging us directly from your article.