Newsletter email subscribers

[meysam81]

Hey, great people,

It goes without saying that you're doing an awesome job.

I wonder if there is anyway we can grow a newsletter and asking people for their emails; one which will be used to push new posts right into their inbox.

I have seen Adding buttons.

I have also seen this discussion in this repository.

Yet, I am not sure how this functionality works. Do you, e.g., use ConvertKit or something similar to get their emails? And what happens after that? Do you mkdocs build the docs and use offline plugin to send one HTML file to their inbox? Do you manipulate the DOM in a customized way? Would you say that Mailchimp does this out of the box?

I'm a bit unclear as to how to grow a newsletter with email subscribers the same way you'd have in platforms like Medium or Substack.

Much appreciated in advance.

[kamilkrzyskow]

Hello @meysam81,
I don't have experience with neither growing a mailing list nor using Medium/Substack, but I might be able to point you in the right direction or at least start the discussion 😅

1. As far, as I know Material for MkDocs has no newsletter and the buttons in the docs are simply example of generic call to actions.
   I also think that providing more explicit instructions on how to grow a mailing list is outside of the project's scope. However, I can see your point that people might migrate from other blogging platforms here, and might expect a swap-in solution for newsletters.

2. In the discussion you mentioned Tim Vink talks about his MailChimp integration, we can see the rendered blog and the source code here:

   • https://timvink.nl/blog/
   • https://github.com/timvink/personal-site/blob/main/docs/blog/index.md?plain=1

   We can see that's a HTML form which sends data to a specific web address, he got (I'm assuming) from his MailChimp account dashboard form action="https://timvink.us20.list-manage.com/subscribe/post?..., so that's how he gets the emails.
   If you want to get more info about what happens next, just ping Tim in this thread. You likely can schedule weekly posts that will be sent to the list.
   Based on his call to action "Get notified of new posts" I would assume his list sends a generic message like "Tim Vink posted a new article titled ... -> go see the website <-" and funnels the readers back to the website.

   Would you say that Mailchimp does this out of the box?

   Your idea might also be correct, as web scraping isn't that complicated, so they could offer an option to scrape your own site and send it as an email without you having to crank the knobs.

3. I would expect the mailing list manager service to provide some templates for your newsletter. However, it would likely be best to match the look of the website, so it also has to accept some sort* of HTML files as your content. The issue is that the offline plugin likely won't help here, as it only changes some things to make sure that the website is "functional" when running from the filesystem. It still has relative paths to CSS/JavaScript assets, pages still contain the navigation tree, and it still loads the search bar.
   *So I think you would need to define a custom template file, similar to the home.html override template, but for an article that will be posted to your newsletter. This template would need to force absolute direct URLs to your assets, remove navigation items and unnecessary JavaScript, it should be a plain HTML page styled same as your actual blog page. Just copy the base.html and modify it until you get a satisfactory result.

*I can imagine some sort of security/optimization measure that doesn't allow customization of the email HTML structure too much, and only allows to style the structure provided by the mailing list manager, so best to check the capabilities before diving into custom template creation.

---

Sorry for the lack of specifics, and I hope my rambling helped you in some way.

[timvink]

Hello, Tim here :)

Setting up email subscriptions to a static site is something completely separate from mkdocs. There are two components basically:

1. Collecting email addresses. I used a form supplied by Mailchimp, and improved the layout a bit using HTML/CSS
2. Triggering email campaigns to your subscribers. I setup Mailchimp to check every night my website's RSS feed, and send out the newest post as an email.

To get the RSS feed from my mkdocs-material blog, I used the mkdocs RSS plugin.

Good luck!

[meysam81]

@squidfunk

I've been trying different things related to the topic of this discussion.

Based on my understanding, the best way to achieve a newsletter-like with mkdocs blogs is probably some manual manipulation of the DOM to grab the content of the article and pass that as the body of an email-template to the subscribers (whichever platform it is).

Would you say there is something wrong with the following approach? Should I not rely on these class and element names? Is it that just pinning my requirements.txt to a specific version can keep my content safe from breaking? Or is there more to it than that?

document.querySelector('header[data-md-component="header"]').remove()
document.querySelector('div[data-md-component="announce"]').remove()
document.querySelector('div.md-sidebar.md-sidebar--post').remove()
document.querySelector('div.md-sidebar.md-sidebar--primary').remove()
document.querySelector('div.md-sidebar.md-sidebar--secondary').remove()
document.querySelector('aside.md-source-file').remove()
document.querySelector('form.md-feedback').remove()
document.querySelector('footer.md-footer').remove()

document.querySelectorAll('body > :not(div[data-md-component="container"])').forEach(e => e.remove())

[timvink]

I think you're probably overcomplicating things.

Enable this plugin so your website has an RSS feed: https://guts.github.io/mkdocs-rss-plugin/

Then use a newsletter provider (I use the free version of Mailchimp) and point it to the RSS url of your website. It can check daily or weekly for new content, and then send that your subscribers.

HTML email formatting is notoriously tricky. Forget about trying to get the exact same styles and use the email template from your newsletter provider. The content from the RSS feed is inserted. So the RSS plugin already takes care of extracting the body of your blogpost, no need to mess around with the DOM.

[meysam81]

There is a catch, however. The RSS plugin, even when receiving the entire content of the post¹, is going to email the markdown content of your files.

This means, all those admonitions, content tabs, and all the other beautiful elements of Material for Mkdocs are not sent to their inbox as rendered on the website, but fetched from the markdwon file and sent as plain & ugly content.

That is no different than sending the plain .md file; and that can't be worse really!

[timvink]

I see an opportunity for someone to build a newsletter provider that supports the full range python-markdown & extensions :) https://facelessuser.github.io/pymdown-extensions/

A more basic solution is to just send an email with the title, first paragraph and a link to your blogpost

[meysam81]

This second part was what I was aiming for with Mailchimp at the beginning, having realized that the RSS plugin is not sending the rendered HTML but the markdown file.

But then it occurred to me, "if they subscribed to the newsletter, why should they bother open the link and come to the website?", like, "isn't the whole point of subscribing that you will get the content?"

I do not mean to trick the readers/subscribers, and as such, this doesn't look like a sexy approach.

+1 to the opportunity and a heroic opportunist. 💪

[kamilkrzyskow]

After having a quick look at some emails in my inbox, I confirmed 3 things:

• All use inline CSS, some include a <style> tag in the <head>, but no external CSS, which matches the info at:
  https://mailtrap.io/blog/email-css/
• All links to images are absolute, so the default behaviour of relative links in MkDocs would have to be modified, I remember there were some similar requests for this feature in the past 🤔
• For the most part the positioning of items is configured via HTML tables, even when div and p tags are all around, at least one global table is present

So converting a Material for MkDocs page, would entail extracting the external base CSS into either the <style> tag or for better compatibility with various email clients into inline CSS for each element and also it might require converting the layout into a table 🤔

IMO too complicated to be worth the hassle, as each each modification to the HTML via some markdown extension could possibly ruin the rest 😅 Unless there would be specific rules set in place, that a blog post mustn't use XYZ features to make it compatible with email, but that's less than ideal 🤔

[AtticusZeller]

good example here but I don't how he realized it, there no much information in it's repo

[kamilkrzyskow]

The site uses the material theme, while the mkdocs.yml shows readthedocs, so the repository hasn't been updated with the latest files.

As for the "Subscribe" button opens a Bootstrap modal, and in that modal there is an iframe with sibforms.com link, which seems to refer to Brevo Forms.

There is also this odd comment:

DON'T FORGET TO CHANGE LINK INSIDE docs/overrides/newsletter.html and mkdocs.yml 

which I wouldn't make for myself personally, so perhaps this is a public template, available somewhere.
However, with the current state of search engines, I could not find anything 🤷

Anyway, the comment implies usage of template overrides with the required form embed:

• https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme

[AtticusZeller]

thank you for such professional explanation 😊@kamilkrzyskow