Feature Requests

Nov 22, 2023

Note: This is part of a series called Using Substack. If this section has been helpful, you might find other resources in this series helpful as well.

The Substack team has done a lot of work to build a platform that’s really useful. I appreciate the work they’ve done to build a newsletter platform that also supports an online archive of posts. I could self-host a newsletter, but I’d much rather spend my time programming and writing than dealing with hosting. So I hope the platform continues to evolve and improve.

This is a list of the features I’d like to see, based on my ongoing experiences publishing through Substack. If you have thoughts on any of these requests, please feel free to comment or otherwise get in touch.

Writing and Editing Posts

The Substack post editor is fairly straightforward to work with, but there are some areas that could be improved significantly.

Please implement more fully-featured code blocks

There are a growing number of technical writers on Substack, but the code blocks we get to use look straight out of the early 2000s. This doesn’t just make code blocks less appealing visually; more importantly the lack of styling options makes it more difficult to write clearly about code. And Substack is all about helping people write well, isn’t it?

Substack’s code blocks are much more plain and less featured than most platforms’ code blocks. This isn’t just an aesthetic issue; the lack of features makes it more difficult to write clearly about code.

I’ve heard the argument that code blocks must be plain because they need to be rendered in a wide variety of email clients. That argument seems pretty weak; Substack emails already ship with a lot of CSS, and you can make code blocks much more functional without adding a lot of weight to emails.

Here are the specific improvements I’d like to see made to code blocks:

Allow code blocks to have headers. This is particularly useful for showing filenames.
Allow code blocks to have highlighted lines. This makes it easier to show which lines have changed compared to a previous listing. It also makes it easier to reference specific lines in the text.
Allow code blocks to have line numbers. This is one of the simplest ways to make it easier to reference specific lines.
Consider adding support for syntax highlighting. This is the one improvement that may require more CSS than it’s worth. Although, you could probably write a minimizer that would only include the CSS that’s used in any given code block.

I wrote an article a while back called Improving code blocks in Substack newsletters. The post takes an existing Substack code block, and rewrites it with a few simple style rules to make it more functional. This is technically feasible, even though posts are rendered in a variety of email clients. This would also require no changes to the current post editor.

Sample rendered email with a code block. The code block has the title "hello.py". — With a relatively small amount of additional CSS, Substack could offer support for headers in code blocks, among other improvements. See MP #19.

Many writers resort to using screenshots instead of code blocks. This requires them to host the code files somewhere else, in order to give readers access to the actual text in the file. It’s also terrible for accessibility, unless screen readers are parsing text from screenshots more accurately than I’m aware of.

Please make the alt text input box a textarea

Unless you’ve focused on accessibility issues, or know someone who uses assistive technology such as a screen reader, alt text is much more important than many people realize. Here’s the current alt text entry box:

We can read about four or five words at a time in this box. Alt text descriptions should be short, but they often need to be longer than just a few words. This is especially true for technical content. I often compose my alt text in a separate text editor, and then paste them into this box.

A multiline text area would allow people to see their entire alt text descriptions, and do a better job of composing accurate and effective messages.

Note: If you’re unclear about what should go into an alt text description, take a look at this resource from the American Foundation for the Blind, and this resource from Harvard’s Digital Accessibility Services.

Let writers select the preview image for pages

On regular posts, the Settings page allows you to choose which image is used in the post preview. There’s no way that I can see to set the preview image for pages like this one. Can we have the option to set that?

Reader Blurbs

Blurbs for the welcome page can only come from other Substack writers, which is fairly limiting because there are far more readers than writers. Substack lets new paid subscribers send messages to newsletter authors when they sign up. When a new paid subscriber shares a message, Substack sends an email with the following message:

_____ agreed to let you share their message, so we’ve created some images for you to share on other social networks. Download your images and share with a link to your publication!

I’d love to be able to show these messages on my publication’s Welcome page. I don't want to share these messages on other social networks, I want people who are deciding whether to enter their email address to see them!

"Your posts are very detailed and easy to understand. Thank you." — This is the kind of blurb I’d like to display on my Welcome page. But it came from a reader, not a Substack author, so I can only share this on social media.

Office Hours

This is a short list of changes that would make Office Hours more enjoyable and manageable for Substack writers and staff. To their credit, Substack is aware of most of these issues, and are working on a number of fixes. Most of these things are a result of the significant growth they’ve experienced over the last few years.

Please continue to structure Office Hours as topical discussions.

The best Office Hours sessions have occurred when they’ve been structured as several separate discussions. For example the breakout discussions focused on New Writers, Grow, and Product were much better than the single-threaded discussions. There will always be people focused on each of these areas, and mixing them all together makes for a lot of noise in the conversations.

Please turn off automatic reloading on the busier Office Hours discussion pages.

This is the main reason the pages are so jumpy. That jumpiness isn’t just annoying; it causes comments to disappear in a way that people who were reading them can’t find them again. It also causes people to lose replies as they’re writing them, if a significant enough refresh happens before their reply has been submitted.

Please add a “Load all comments” button to the busier pages.

This would return a really long page, but it would allow people to use Ctrl-F to find any of their own comments in the discussion, and any comment that they remember a snippet of.

If the pages are truly too long to load in their entirety, please offer a couple buttons, maybe the default “Load more” and one or two more along the lines of “Load 100 more”.

On a single-comment page (the page that loads when you click a comment’s timestamp), please add a link to the parent comment.

The fact that timestamps link to separate pages is the best thing available to make long discussion threads manageable. Thank you for that! However, if you’re not looking at a top-level comment, there’s no way to reliably move back up the comment chain. The only link back is the “Return to thread” link, which often seems to dump you back to the main discussion page.

Note: For more about Office Hours, see the Office Hours survival guide. Because Substack staff is actively working on improving the site, some of these features may already be implemented. If they’ve been implemented in a consistent way, please let me know and I’ll be happy to update this list.

Mostly Python