dask / dask/dask-blog

Modernise blog

Open
#178 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
30
Forks
35
PR merge metrics
No merged PRs in 30d

Description

A couple of years ago I [attempted and abandoned rebuilding this blog](https://jacobtomlinson.dev/posts/2023/the-challenge-of-updating-an-aging-blog/) with more modern tooling and styles.

I wanted to revisit this and see how much effort it would take to update the blog given the explosion in the ability of agents over the last few months.

In my last attempt I set out the following criteria for rebuilding the tooling for this blog

### Must

- Posts **must** be able to be written in markdown.
- Posts **must** support ["dollar math"](https://mystmd.org/guide/math) for maths and equations.
- The blog **must** fit with the [Dask Branding Guidelines](https://www.dask.org/brand-guide).
- The blog **must** have modern HTML metadata and preview images to perform well in search.
- Posts **must** be able to set the canonical header to point to original content.
- Anyone **must** be able to submit a new post easily without manual human interaction.
- Reviews **must** be performed in an open way such as in PRs on GitHub.
- Any Dask steering council member **must** be able to publish content to the blog.
- Readers **must** be able to subscribe via RSS.

### Should

- The blog _should_ be built using a tool familiar to Python developers.
- Posts _should_ allow comments (the current blog uses Disqus).
- Posts _should_ support custom JavaScript, CSS and HTML for when authors want to go off-road.

### Could

- Posts _could_ use [MyST](https://mystmd.org/) to reduce the amount of custom HTML that is used.
- Posts _could_ be written in [Jupyter Notebooks](https://jupyter.org/).

The approach I took in 2023 was to try to port the blog to Sphinx + ablog, given the amount of expertise in the Dask community around Sphinx. However it felt like the tool was fighting me at every turn and was part of the reason why I abandoned it.

This time I decided to explore multiple tools in addition to updating the blog to meet the requirements above. My goal was to port the blog to multiple frameworks and compare and explore what the project would look like when built with those tools. Then once I had a functioning blog with each tool I could explore updating the design for each one in a way that fit with the tool. This wouldn't have been possible without coding agents.

Last time I spent a day on it and got part way through updating the blog. This time I spent a day on it and created three different versions of the blog, all with new or updated frameworks, new updated designs and I even had time for some benchmarking using Lighthouse. I actually cloned the repo three times locally and had three instance of Claude Code running in parallel, one on each repo. This allowed me to switch between them and push them independently.

I'll open draft PRs for each one and get Netlify to run a preview build for each one so folks can compare them. The design of each one is slightly different due to the non-determinism of AI models. I'm not especially interested in comparing the design in any detail because any one of them can be prompted more to fix up any design issues. I'm mainly interested in comparing the different project structures, build tooling and framework features/limitations.

The design differences are interesting though. Each tool has taken a slightly different approach and each preview has different features. For example one added light/dark mode, another used cards for the index page instead of a list. I'm quite enjoying comparing the three and picking out things about the designs I like.

Once I've chosen a tool that I'm happy with I'll discard the other two and nudge the chosen one forward incorporating everything I've learned from this experiment and incorporating any design elements from the other two that I particularly liked.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the listed must, should and could requirements, then compare the multiple blog implementations and their preview builds once available. Done means selecting a tool and design that meet the required authoring, publishing, metadata, branding and RSS criteria, with the alternatives discarded.

Written by the indexing model from the issue text.

Assessment

Tech stack
html, jupyter-notebook, markdown
Domain
content, tooling, web-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.