Uh oh!
There was an error while loading. Please reload this page.
chore: redesign in Astro - #2169
Conversation
Co-authored-by: Sebastian Beltran <bjohansebas@gmail.com>
✅ Deploy Preview for expressjscom-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Co-authored-by: shubham oulkar <91728992+ShubhamOulkar@users.noreply.github.com> Co-authored-by: Sebastian Beltran <bjohansebas@gmail.com> Co-authored-by: Shubham Oulkar <oulkarshubhu@gmail.com>
Co-authored-by: shubham oulkar <91728992+ShubhamOulkar@users.noreply.github.com>
Co-authored-by: shubham oulkar <91728992+ShubhamOulkar@users.noreply.github.com>
Co-authored-by: shubham oulkar <91728992+ShubhamOulkar@users.noreply.github.com> Co-authored-by: Shubham Oulkar <oulkarshubhu@gmail.com> Co-authored-by: Sebastian Beltran <bjohansebas@gmail.com>
Co-authored-by: Shubham Oulkar <oulkarshubhu@gmail.com>
Co-authored-by: Shubham Oulkar <oulkarshubhu@gmail.com> Co-authored-by: Sebastian Beltran <bjohansebas@gmail.com>
Co-authored-by: Shubham Oulkar <oulkarshubhu@gmail.com> Co-authored-by: Sebastian Beltran <bjohansebas@gmail.com>
Co-authored-by: Sebastian Beltran <bjohansebas@gmail.com>
Signed-off-by: Sebastian Beltran <bjohansebas@gmail.com>
bjohansebas
commented
Apr 11, 2026
the same thing happens in Node.js and Fastify as well. I’m already asking the Orama team where I can get those images to fix it. |
| expressjs express master/examples | ||
| LIST_END | ||
| ) | while read org repo branch; do | ||
| # TODO: change the DEST when astro project is in the root of the repo instead of in a subdirectory. |
There was a problem hiding this comment.
This has already been fixed, I just forgot to remove the comment.
jonchurch
commented
Apr 15, 2026
Im working through reviewing, will likely PR some changes to the redesign branch directly (mostly github actions related stuff is what Im finding some fixes for, many are things that already existed that Im just noticing now) but tryna do the review on the full context here in this PR. But things are looking really good! Some TODOS I have written down right now, updating the references to the redesign branch in GHA to be main. Those are last step things though of course as it would break the actions for the redesign branch before it lands. Id prefer to keep the git history of the repo all parented to the same root. Meaning, I think we should land to gh-pages and then just rename the branch to main to keep all the history, vs starting from scratch with a new branch entirely that has a new root. Thoughts? |
bjohansebas
commented
Apr 15, 2026
Sounds good to me. I just wanted to keep a separate branch with the old site just in case (also as a source of truth for the documentation, since there were some changes, I already mentioned them in the PR description). But that can literally be created separately, and we can merge this into gh-pages, and then rename it to main if we want. |
This comment was marked as off-topic.
This comment was marked as off-topic.
This comment was marked as off-topic.
This comment was marked as off-topic.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
| # node-version-file: ".nvmrc" use when .nvmrc is on root of the repo | ||
| node-version: '24.13' | ||
| # cache: "npm" use when package-lock.json is on root of the repo |
There was a problem hiding this comment.
Since #2253package-lock.json and .nvmrc are in the repository root.
| # node-version-file: ".nvmrc" use when .nvmrc is on root of the repo | |
| node-version: '24.13' | |
| # cache: "npm" use when package-lock.json is on root of the repo | |
| node-version-file: '.nvmrc' | |
| cache: 'npm' |
| PUBLIC_ORAMA_PROJECT_ID: ${{ github.event_name == 'push' && secrets.PUBLIC_ORAMA_PRODUCTION_PROJECT_ID || secrets.PUBLIC_ORAMA_PROJECT_ID }} | ||
| PRIVATE_ORAMA_API_KEY: ${{ github.event_name == 'push' && secrets.PRIVATE_ORAMA_PRODUCTION_API_KEY || secrets.PRIVATE_ORAMA_API_KEY }} | ||
| PUBLIC_ORAMA_DATASOURCE_ID: ${{ github.event_name == 'push' && secrets.PUBLIC_ORAMA_PRODUCTION_DATASOURCE_ID || secrets.PUBLIC_ORAMA_DATASOURCE_ID }} |
There was a problem hiding this comment.
Do these "non-production" secrets exist? CI on pull requests fails (e.g. here) with Endpoint and API Key are required to create a Profile, because the API key is missing (PRIVATE_ORAMA_API_KEY).
There was a problem hiding this comment.
They do exist, but they don't work on forks since they are secrets. So what we would need to do is either prevent this workflow from running on forks, or use pull_request_target, although I’d prefer to avoid that.
There was a problem hiding this comment.
pull_request_target sounds like a bad idea.
According to actions/runner#1138, if: github.repository_owner == 'expressjs' && github.actor != 'dependabot[bot]' (or if: github.repository == 'expressjs/expressjs.com' && github.actor != 'dependabot[bot]') should skip the job in runs that do not have access to secrets (Dependabot runs from the same repo, but does not have access to secrets)
There was a problem hiding this comment.
Yep, do you want to open a PR? As some of you already know, I have to step away from the project, so I won’t be around here for about a month.
There was a problem hiding this comment.
Of course it wasn't so simple and the if from comment above did not work - #2297.
Co-authored-by: Crowdin Bot <support+bot@crowdin.com> Co-authored-by: Sebastian Beltran <bjohansebas@gmail.com>
wesleytodd
left a comment
There was a problem hiding this comment.
LGTM! Thanks for all the great wrok on this everyone. Really looking awesome.
Preview Url :- https://deploy-preview-2169--expressjscom-preview.netlify.app/
Important
The conflicts will be resolved when we’re ready to release it to the public, so don’t worry about that—one of the captains will handle it when the time comes.
Overview
The design aims to closely follow the original Figma as much as possible. However, due to time constraints, it was not feasible to keep it fully up to date, as Orama supported the redesign effort until April 3.
Throughout the development process, feedback was continuously gathered via Slack, and adjustments were made iteratively as the site evolved.
As part of this transition, and to provide a clear before-and-after reference for the API content, the
gh-pagesbranch will be left untouched, while a newmainbranch has been introduced, which will become the default branch of the repository.The following sections outline the key decisions that were made and explain why certain aspects of the site are implemented the way they are.
For more in-depth details on how the site works, everything is documented in the repository under the
docsfolder.API Routes
At the beginning, each method and property had its own URL. Over time, we decided to group them by object (
req,res,app,router) to reduce both build times and page size.Previously, the site could reach up to 600MB due to all generated i18n pages. With this change, the build process is now significantly faster and more efficient.
Search
The original Figma proposal placed the search as a right-side panel. This was changed to a modal-based search, mainly because the original design didn’t account for having a Table of Contents (ToC) per page.
Important note:
This is the only part of the site that uses React. It was implemented following Orama’s recommendation to ensure a fast and high-quality search experience.
Menu
Compared to the Figma design, the language switcher and dark/light theme toggle were moved next to the search.
This follows a pattern similar to the Node.js website.
Versioning
The Figma design did not include page versioning. During development, we decided to introduce versioning for documentation pages.
How versioning works is documented in the repository under the
docsfolder.i18n
The versioning system remains intact.
Current issue:
For now:
Once fixed:
Footer
The original footer design did not follow the foundation’s recommendations.
It was updated to include the proper copyright text, which was later also added to the current expressjs.com site.
E2E testing
Setup playwright testing platform with GitHub actions. Total 48 tests are added for
hero, features, theme, i18n and footercomponents.Test Artifact download URL: https://github.com/expressjs/expressjs.com/actions/runs/24755732707/artifacts/6568925216
Updated Documentation
During this process, several parts of the documentation were improved:
Example:
https://deploy-preview-2169--expressjscom-preview.netlify.app/en/resources/middleware/body-parser/
More documentation will continue to be improved over time throughout the year with the team.
API Overview
The API now includes an overview section, improving organization and aligning with the new versioning system.
llms.txt
Support was added to generate
llms.txtfiles from the documentation.This allows language models to better access and understand the docs:
https://deploy-preview-2169--expressjscom-preview.netlify.app/llms.txt
OG Images
All pages now have dynamically generated Open Graph images.
Note:
Homepage Announcement Banner
The homepage banner is now automated:
This behavior is documented in the
docsfolder.CI: Broken Link Detection
Accessibility
Light Mode
Issues Resolved
The following issues were closed as part of this migration (and likely more):
Final Notes
Personal Note of Sebastian
Important
I’d really like to be the one to press the merge button.
The main reason I joined Express was to improve the documentation experience, and this represents the biggest step in that direction. After all the time and effort I’ve invested into this, it would mean a lot to me.
If anything needs to be fixed quickly before launch, I’m happy to jump on it and address it right away.
Summary of commits
Summary of commits
Infrastructure / Setup
Set up the Astro project from scratch, configured the Netlify deployment, and later moved the Astro project from a subdirectory to the repository root.
Details
CI/CD
Added GitHub Actions workflows for building, linting, and checking links on PRs. Set up Husky for pre-commit hooks, Dependabot for dependency updates, and fixed the Crowdin configuration for translations.
Details
Design / UI Components
Built the full site layout: responsive header and sidebar navigation (mobile, tablet, desktop), footer, homepage hero with optimized WebM/WebP media, features/banner sections, reusable Alert component, blog post page, breadcrumb, and documentation page layout adjustments.
Details
Features
Implemented i18n language selection, blog listing page, and search/chat powered by Orama. Added SEO essentials (sitemap, robots.txt, RSS feed, Open Graph/Twitter Cards, automatic OG image generation). Built documentation features like Table of Contents, prev/next navigation, and rehype plugins for heading links. Added support for global pages, content collections, redirects for legacy links, multi-language translation editing, scripts for pulling external docs, and LLM-friendly API endpoints. Bumped to Astro v6.
Details
Documentation
Wrote overviews for the Application and Express objects and improved API overviews. Migrated remaining Jekyll includes to Astro. Unified headings and API pages for consistency. Adopted the new Alert component across docs. Added security.txt, clustering/middleware images, and project structure documentation. Improved the v5 migration guide (including documenting removed options) and updated routing docs for separate versions.
Details