Eco-friendly docs

Estimates for the climate impact of the web industry range from between 2% and 4% of global carbon emissions, roughly equivalent to the emissions of the airline industry. There are many complex factors in calculating the ecological impact of a website, but this guide includes a few tips for reducing the environmental footprint of your docs site.

The good news is, choosing Starlight is a great start. According to the Website Carbon Calculator, this site is cleaner than 99% of web pages tested, producing 0.01g of CO₂ per page visit.

Page weight

The more data a web page transfers, the more energy resources it requires. In April 2023, the median web page required a user to download more than 2,000 KB according to data from the HTTP Archive.

Starlight builds pages that are as lightweight as possible. For example, on a first visit, a user will download less than 50 KB of compressed data — just 2.5% of the HTTP archive median. With a good caching strategy, subsequent navigations can download as little as 10 KB.

Images

While Starlight provides a good baseline, images you add to your docs pages can quickly increase your page weight. Starlight uses Astro’s optimized asset support to optimize local images in your Markdown and MDX files.

UI components

Components built with UI frameworks like React or Vue can easily add large amounts of JavaScript to a page. Because Starlight is built on Astro, components like this load zero client-side JavaScript by default thanks to Astro Islands.

Caching

Caching is used to control how long a browser stores and reuses data it already downloaded. A good caching strategy makes sure that a user gets new content as soon as possible when it changes, but also avoids pointlessly downloading the same content over and over when it hasn’t changed.

The most common way to configure caching is with the Cache-Control HTTP header. When using Starlight, you can set a long cache time for everything in the /_astro/ directory. This directory contains CSS, JavaScript, and other bundled assets that can be safely cached forever, reducing unnecessary downloads:

Cache-Control: public, max-age=604800, immutable

How to configure caching depends on your web host. For example, Vercel applies this caching strategy for you with no config required, while you can set custom headers for Netlify by adding a public/_headers file to your project:

/_astro/*
  Cache-Control: public
  Cache-Control: max-age=604800
  Cache-Control: immutable

Power consumption

How a web page is built can impact the power it takes to run on a user’s device. By using minimal JavaScript, Starlight reduces the amount of processing power a user’s phone, tablet, or computer needs to load and render pages.

Be mindful when adding features like analytics tracking scripts or JavaScript-heavy content like video embeds as these can increase the page power usage. If you need analytics, consider choosing a lightweight option like Cabin, Fathom, or Plausible. Embeds like YouTube and Vimeo videos can be improved by waiting to load the video on user interaction. Packages like astro-embed can help for common services.

Did you know?

Parsing and compiling JavaScript is one of the most expensive tasks browsers have to do. Compared to rendering a JPEG image of the same size, JavaScript can take more than 30 times longer to process.

Hosting

Where a web page is hosted can have a big impact on how environmentally friendly your documentation site is. Data centers and server farms can have a large ecological impact, including high electricity consumption and intensive use of water.

Choosing a host that uses renewable energy will mean lower carbon emissions for your site. The Green Web Directory is one tool that can help you find hosting companies.

Comparisons

Curious how other docs frameworks compare? These tests with the Website Carbon Calculator compare similar pages built with different tools.

Framework	CO₂ per page visit
Starlight	0.01g
VitePress	0.05g
Docus	0.05g
Sphinx	0.07g
MkDocs	0.10g
Nextra	0.11g
docsify	0.11g
Docusaurus	0.24g
Read the Docs	0.24g
GitBook	0.71g

Data collected on 14 May 2023. Click a link to see up-to-date figures.

More resources

Tools

• Website Carbon Calculator
• GreenFrame
• Ecograder
• WebPageTest Carbon Control
• Ecoping

Articles and talks

• “Building a greener web”, talk by Michelle Barker
• “Sustainable Web Development Strategies Within An Organization”, article by Michelle Barker
• “A sustainable web for everyone”, talk by Tom Greenwood
• “How Web Content Can Affect Power Usage”, article by Benjamin Poulain and Simon Fraser