Replacing our blog

[agjohnson]

We haven't explicitly talked about it, but Pelican is usually used for blog content -- EthicalAds uses Pelican for site and blog content. So I have been assuming that the plan was to follow the lead of EA and author all site content here.

So the main question here: what are we doing with the existing blog content?

Behind door A: keep the old blog around, archive it, and link to it where necessary. New blog content is in Pelican, under /blog/. This is the least amount of work. I'll say this is my vote.

Behind door B: port old content to Pelican, where it can be displayed nicely, we have a nice history of posts, and don't have to worry about the split. This is a medium amount of work. Our blog doesn't get a lot of traffic, and probably less so on historical posts. So probably a lot of work for not a whole lot of value.

Behind door C: blog content stays where it is we don't use Pelican for blog posts. I'm not as excited about this plan and assume we are all ready to drop our current authoring workflow. But this is still an option.

Thoughts?

cc @readthedocs/advocacy

Work:

• Fix up blog templates here -- handled with Fix blog templates #201
• Output 1 article on RSS feed so our newsletter integration works -- handled in Fix blog templates #201
• Test RSS feed on production, the URL of the feed looked wrong in PR preview on Example blog posts #202
• Translate Sphinx reST to Pelican reST -- Pelican posts use front matter, not a Sphinx directive
• Point links for blog to /blog/, archive old blog (?)

[astrojuanlu]

What would be the benefits (for authors or for readers) of using pelican? Not trying to be nitpicky here, just wondering what value we will get from whatever effort we invest.

[agjohnson]

Not nitpicking at all, that's good framing!

For readers, our blog would be integrated with our new site content, and so the styles would be more mature. No one does any work on our CSS, so that has rotted. Our current blog could be switched to use a generic theme, but that would look a bit sloppy on our part. The work required to integrate our blog with our site content is minimal, given we're already doing the work to move website content to Pelican. So Pelican has a slight advantage here for readers, but there aren't features of Pelican on their own that would warrant moving the blog otherwise.

It also has a slight advantage for our overall presence, and what level of polish we're communicating to customers and users. Details like this communicate our preferred level of polish and maturity, and a mature product is easier to sell. Not that users would see our blog and be dissuaded from our product, but users/customers will put puzzle pieces together and changing minds is hard.

Authoring, it would be great to have content produced in one place. So that's a slight advantage. Otherwise the experience is comparable to our blog now, there's no huge advantage that I know of, but EA team might have more opinions there.

I'll add that if we can reduce to one property for our blog, or just gently abandon that content perhaps, that would be one less thing to maintain. I will continue to be the broken record here: with limited resources, we need to maintain fewer things.

[agjohnson]

Also, for my own vote, I suppose if content is easy to copy over and we can automate that, I would be +1 on migrating content. I could see some Sphinx specific content tripping up Pelican though.

[pradyunsg]

One thing I'd flag is to be mindful of not breaking existing URLs under https://blog.readthedocs.com to the blog posts + any potential SEO implications of such a move. You might lose the existing SEO reputation, which could be good or bad, depending on what it is. :)

[ericholscher]

I think we should be able to port the content pretty reasonably. A couple small things might break, but I agree not breaking the old links is good. Even if some of the fiddly bits of Sphinx don't work, we should be able to get 95% of the content with pandoc.

[agjohnson]

Yeah, perhaps just a warning about the content being archived on the page is enough. Pelican can do reST source, so we'd probably mostly just lose intersphinx links and have to re-write the frontmatter/whatever.

I'd say let's give it a quick shot and see what it looks like. If we're happy with 95% of the posts, that sounds like a win.

[agjohnson]

So far, looks like we at least need to translate our blog metadata from a post directive to a field list.
It will be slightly annoying to automate if we want to go that route, but doable.

Pelican expects this https://docs.getpelican.com/en/3.6.3/content.html#file-metadata

We still need to test intersphinx and other features.

[nienn]

Made a working test with the latest blog post here #57. File metadata and Cross-Referencing had to be edited to make build pass.

[agjohnson]

I fixed up the blog templates with:

• Fix blog templates #201

And I added some example ported blog posts with:

• Example blog posts #202

Porting the posts did take some removal of intersphinx links and the front matter, but was very straight forward.

For full backporting of all our posts:

• We'd have to automate translation of the front matter, it wouldn't take too much effort
• We'd have to alter intersphinx links, though there aren't too many posts that need updated in this way
• We'd want to include linked files with the posts, which would be harder to automate, and would require some rewriting of the image/etc URLs in the new posts
• Posts will get the same default image for the blog post if we don't update it

After a blog post is published, we usually see a big drop in new visitors, almost to nothing. So, it seems like the least amount of friction to actually using Pelican for blog posts would be to archive the blog.readthedocs.com -- keeping the URL and links the same -- and bring over some number of backported posts to fill up the post history more here.

I'll update the list in the description, I handled a few more tasks in #201 to get us ready to use this for our blog posts.

[ericholscher]

I'm 👍 on archiving. We can note it on the post introducing the new blog, and call it a day I think. I can try and write a newsletter with the new format perhaps.

One idea I had was just migrating the posts from HTML -> md via Pandoc, instead of trying to go RST -> MD. That solves most of the intersphinx & front matter issues. Not sure if that makes it worth doing?

[agjohnson]

Yeah, I'd say give a try first as well. I don't think we'll have too many places where our authoring patterns change much at all.

If we convert anything, any reason we need markdown at all? For the tests so far, we've been going reST -> reST, just removing Sphinx-specific features link intersphinx links. These are pretty easy to swap to normal HTTP links and the format of the meta data/front matter updates really easily from the Ablog directives so far.

For new posts, I don't have strong preference on markdown vs reST, though I'd probably write posts in reST just to have definition lists 🙂

[ericholscher]

Ah gotcha -- we're using md on the ad side, which I figured we'd try to keep stuff similar, but it seems like the sites are pretty divergent at this point, so maybe that doesn't make sense? 🤷

[ericholscher]

@agjohnson Looking at your PR with the ported website migration post, I wonder about including that in the work for the launch here? It seems like it's pretty much done! I can try and debug the RSS issue, and I think we can just swap over to writing on the new site?

[agjohnson]

Ah gotcha -- we're using md on the ad side, which I figured we'd try to keep stuff similar

Ahhh okay, yeah that makes sense too. I'd be totally fine leaning towards markdown for new posts, and maybe if a post makes sense in reST, that is totally fine too. The metadata at the front of the post is just a little different between the two formats.

It seems like it's pretty much done! I can try and debug the RSS issue

In theory, I think my PR should have been close, but I didn't test the RSS feed and newletter bits at all yet. The URL of the feed is wrong in the page source, those config variables need fixed still. But the actual URL should eventually have some content, as we add published articles:

• https://about.readthedocs.com/blog/feed.rss
• https://about.readthedocs.com/blog/atom.xml

[ericholscher]

@agjohnson I think the RSS issue is here:

website/pelicanconf.py

Lines 10 to 12 in e8bd12a

	rtd_version = os.environ.get('READTHEDOCS_VERSION')
	if rtd_version:
	SITEURL = f'/en/{rtd_version}/'

The project is set to single version, so it will never have a /en/$version/, and just be served at /.

[agjohnson]

Aye, I didn't look into the issue yet at all, but did notice the extra /en/latest in the URLs. I'm actually surprised that hasn't caused more trouble for us yet. Guessing that is the problem here, as the FEED_URL and friends use SITEURL.

[ericholscher]

Pushed up a fix in #205

[humitos]

I'm removing this task from the roadmap since we have been de-prioritizing this work and I don't think we will do it anytime soon. There are more important tasks around marketing we can take on, I'd say.

[agjohnson]

I feel this should still be on our roadmap. The work left here is to start authoring content on the new blog. We can decide what to do with old content, but this fell off because of the mailerlite configuration needed to be adjusted to the new blog.

The reason we want this is to continue to provide our website with as much traffic as possible, where the current blog and websites do not promote this much at all. The authoring patterns will be nicer with blog posts written on our website as well.

I'm going to put this on our roadmap, but leave it in the backlog. I'd like to have it in a place where we can discuss priority.

[ericholscher]

I can try writing a newsletter post on the new blog, but yea, we need to hook up the email automation. It's not a ton of work, but I'm scared to mess with it after all the mail sending issues we've had 🙃

I guess I can configure a new mailerlite config, and keep the old blog one setup -- that way we can roll back if needed.

[agjohnson]

Ah yeah, that seems like safe way to test things out. I don't think there will be any big surprises on the authoring side at least, but we also haven't used it yet so there could be some small bugs to squash.

I put up #246 to provide some link back to the old content too, as well as some subscribe links. I imagine we'd redirect blog RSS feed requests from the current blog to the website blog, and mailerlite should point to the right blog as soon as we reconfigure things.

If we need some period with overlap, we can syndicate posts on both too. Newsletters especially should just copy over.

• Add blog intro pointing towards subscription and archived blog #246

[ericholscher]

Everything is ready here, just trying to finish up the mailerlite integration.

[ericholscher]

The newsletter went out properly today 🎉

[ericholscher]

I think we can likely call this done, unless we want to keep it open to track moving old content over.

[agjohnson]

I think we could call the initial cut over done, though there are a few pages we should port over eventually:

• Anything we've linked to from the dashboard, ie deprecation notices pointing to our blog posts
• Anything getting significant traffic after initial posting -- looks like just mostly the above though

I don't care too much about losing other post history here, we'll build up a post backlog here pretty quickly.

So, if it seems reasonable to do now, those pages could port over now too.

[ericholscher]

Info for updating this: https://plausible.io/blog.readthedocs.com?period=12mo&keybindHint=L