Skip to content

docs: blog: draft new website post #143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
thibaudcolas wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: blog: draft new website post #143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions blog/2025-11-19-a-shiny-new-website.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: "A shiny new website"
authors: thibaudcolas
---

With design updates, fancy new features ✨, and opportunities for further improvements.

<!-- truncate -->

This site’s design and implementation have been more or less the same in 7 years! I thought it was time for an upgrade.

## The 2018 website

I decided to set up a standalone docs site for Draftail back in October 2018, and set up the site with [Docusaurus](https://docusaurus.io/) v1. I think it looks pretty good:

![Screenshot of the Draftail homepage with 2018 design](./assets/a-shiny-new-website/draftail-design-2018.png)

I chose Docusaurus because I really like building web content as well as as apps with React ergonomics, and Docusaurus is just the right combination of opinionated defaults for this, geared towards fully static sites. No server but also little to no need for client-side JavaScript. Most of this site’s setup was copied from [Draft.js website](https://draftjs.org/).

I also really liked how compared to other docs website generators, there was a clear blogging component. I wish more technical docs included a bit of blogging. It’s nice for releases announcements but also for other aspects of the project!

## Why the upgrade

The biggest drawback with the 2018 site was accessibility issues, which weren’t possible to resolve within the opinionated Docusaurus v1 setup without extensive overrides, otherwise it could have been deemed good enough in perpetuity - I didn’t see big reason to chase updates. In addition, I’ve also wanted to trial a few improvements to the site, and it feels better to experiment within a fresher setup!

I briefly considered alternatives like [VitePress](https://vitepress.dev/) and [Starlight](https://starlight.astro.build/). They’re nice and shiny, seem to provide similar ergonomics, but not be opinionated enough. It would require plugins and custom development to get the features I’m after:

- Blogging. Certainly something I don’t want to reinvent.
-
Copy link

@coderabbitai coderabbitai bot Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Complete the empty bullet point.

Line 29 contains a bare - with no following content, indicating incomplete markup.

Apply this fix to remove the incomplete bullet:

- Blogging. Certainly something I don't want to reinvent.
-

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents 
In blog/2025-11-19-a-shiny-new-website.md around line 29 there is a bare list
marker "-" with no content; remove the empty bullet or replace it with the
intended list item text so the markdown list is complete and no blank list
element remains.


## Future features

[llms.txt](https://llmstxt.org/)

[Ask AI](https://docsearch.algolia.com/docs/v4/askai/) with [OpenRouter](https://openrouter.ai/)

SEO https://docusaurus.io/docs/seo
Copy link

@coderabbitai coderabbitai bot Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Wrap bare URLs in markdown link syntax.

Multiple URLs violate markdownlint rule MD034 and should be wrapped in proper markdown link format. This improves readability and makes links clickable in markdown viewers.

Examples:

-SEO https://docusaurus.io/docs/seo
+[SEO](https://docusaurus.io/docs/seo)

-https://docsearch.algolia.com/ issues indexing
+[Algolia DocSearch indexing issues](https://docsearch.algolia.com/)

-https://pagespeed.web.dev/analysis/https-www-draftail-org-docs-api/rfwgitxncz?form_factor=mobile
+[PageSpeed Insights - mobile analysis](https://pagespeed.web.dev/analysis/https-www-draftail-org-docs-api/rfwgitxncz?form_factor=mobile)

Apply similar formatting to all other bare URLs in this section (lines 39, 49, 51, 53, 55, 56).

Also applies to: 39-39, 49-49, 51-51, 53-53, 55-55, 56-56

🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

37-37: Bare URL used

(MD034, no-bare-urls)

🤖 Prompt for AI Agents 
In blog/2025-11-19-a-shiny-new-website.md around line 37 (also apply to lines
39, 49, 51, 53, 55, 56), there are bare URLs (e.g.,
"https://docusaurus.io/docs/seo") that violate markdownlint MD034; update each
bare URL to use markdown link syntax like [link text](https://example.com) or
inline descriptive text in brackets followed by the URL in parentheses, ensuring
descriptive link text where appropriate and leaving no bare URLs in those lines.


https://docsearch.algolia.com/ issues indexing

[NLWeb](https://github.com/nlweb-ai/NLWeb)

[HUD in Netlify](https://docs.netlify.com/deploy/review-deploys/heads-up-display/)

Dark theme

Multilingual content

https://pagespeed.web.dev/analysis/https-www-draftail-org-docs-api/rfwgitxncz?form_factor=mobile

https://pagespeed.web.dev/analysis/https-69172eea3b977200082d7b3b--draftail-netlify-app-docs-api/27t1cexryr?form_factor=mobile

https://69172eea3b977200082d7b3b--draftail.netlify.app/docs/api

https://angular.dev/ai
https://docs.modular.com/max/coding-assistants/
Comment on lines +31 to +56
Copy link

@coderabbitai coderabbitai bot Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Complete and structure the "Future features" section before publishing.

This section reads like incomplete draft notes rather than finalized blog content. It contains bare URLs, fragmentary descriptions, and lacks coherent structure. Each future feature should be properly described with context.

Suggestions:

  • Either expand each item with a brief description explaining the feature, why it's planned, and its expected impact
  • Or move this section to an internal notes/roadmap document and remove it from the published blog post if the features aren't ready to be publicly discussed yet

For now, at minimum:

  • Replace bare URLs with proper markdown links (e.g., [llms.txt](https://llmstxt.org/))
  • Complete the empty bullet point at line 29
  • Add substantive descriptions or context for each feature
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

37-37: Bare URL used

(MD034, no-bare-urls)

39-39: Bare URL used

(MD034, no-bare-urls)

49-49: Bare URL used

(MD034, no-bare-urls)

51-51: Bare URL used

(MD034, no-bare-urls)

53-53: Bare URL used

(MD034, no-bare-urls)

55-55: Bare URL used

(MD034, no-bare-urls)

56-56: Bare URL used

(MD034, no-bare-urls)

Binary file added blog/assets/a-shiny-new-website/draftail-design-2018.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.