CO2.js v0.18 release (docs update)

public/_redirects

@@ -1,2 +1,3 @@
-/carbon.txt     /   404
-/.well-known/carbon.txt     /   404
+/co2js/explainer/methodologies-for-calculating-website-carbon/  /co2js/models/overview/ 301
+/co2js/methods/     /co2js/functions/overview/    301
+/co2js/data/     /co2js/data/overview/    301

src/_includes/layouts/default.njk

@@ -107,7 +107,7 @@
                       {%- for entry in navPages %}
                         {% if sectionTitle != entry.sectionTitle %}
                           {% set sectionTitle = entry.sectionTitle %}
-                          <li class="menu-title">
+                          <li class="menu-title border-b-2 border-primary">
                             <p class="divider text-sm font-bold font-mono">{{ sectionTitle }}</p>
                           </li>
                         {% endif %}
@@ -175,4 +175,4 @@
     </div>
     {% analytics %}
   </body>
-</html>
+</html>

src/docs/co2js/data/average-intensity.md

@@ -0,0 +1,36 @@
+---
+title: Data - Average intensity
+description: This guide will show you how find and use country-level grid intensity data available in CO2.js.
+eleventyNavigation:
+  key: data-average-intensity
+  title: Average intensity
+  sectionTitle: Data
+  order: 6.2
+---
+
+# Data - Average intensity
+
+You can import annual, country-level average grid intensity data from [Ember Climate](https://ember-climate.org/data/data-explorer/) into your projects directly from CO2.js. For example, if you wanted to use the average grid intensity for Australia in a project, then you can do so by using the code below:
+
+```js
+import { averageIntensity } from '@tgwf/co2/data';
+const { data, type, year } = averageIntensity;
+
+const { AUS } = data;
+console.log({ AUS })
+```
+
+All countries are represented by their respective [Alpha-3 ISO country code](https://www.iso.org/obp/ui/#search).
+
+### Using CO2.js v0.16 and older
+
+If you are using CO2.js v0.16 or older in your code, then you should import data using the code sample below:
+
+```js
+// Import data from CO2.js
+import { marginalIntensity } from "@tgwf/co2"
+```
+
+## Licenses
+
+The carbon intensity data from Ember is published under the Creative Commons ShareAlike Attribution Licence ([CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)). ([What does this mean?](https://www.tldrlegal.com/license/creative-commons-attribution-share-alike-cc-sa))

src/docs/co2js/data/electricity-maps.md

@@ -0,0 +1,48 @@
+---
+title: Data - Electricity Maps
+description: This guide will show you how find and use country-level grid intensity data available in CO2.js.
+eleventyNavigation:
+  key: data-electricity-maps
+  title: Electricity Maps
+  sectionTitle: Data
+  order: 6.1
+---
+
+# Data - Electricity Maps
+
+You can import annual, country-level average grid intensity data from [Electricity Maps](https://www.electricitymaps.com) into your projects directly from CO2.js. For example, if you wanted to use the average grid intensity for **Australia for all available years** in a project, then you can do so by using the code below:
+
+```js
+import { yearly2025, yearly2024, yearly2023, yearly2022, yearly2021 } from '@tgwf/co2/data/electricity-maps';
+
+const data2025 = yearly2025.data["AU"]
+const data2024 = yearly2024.data["AU"]
+const data2023 = yearly2023.data["AU"]
+const data2022 = yearly2022.data["AU"]
+const data2021 = yearly2021.data["AU"]
+
+console.log({ data2025, data2024, data2023, data2022, data2021 })
+```
+
+Electricity Maps also provides information for some grid regions (for example CAISO in the United States, or Northern India). To access these regions, developers should use the appropriate zone ID for the region they wish to access.
+
+Data is available for:
+
+- All Electricity Maps zones (see the [full list of available zones](https://github.com/thegreenwebfoundation/co2.js/blob/main/data/fixtures/electricity-maps-zones.js))
+- The calendar years 2021, 2022, 2023, 2024, and 2025
+
+### Accessing other Electricity Maps data
+
+While we are able to provide annual grid data from Electricity Maps in CO2.js, users wishing to utilise data at higher-than-yearly resolution (e.g monthly, hourly etc.), or [other historical and forecasted datapoints](https://www.electricitymaps.com/data) should contact Electricity Maps to access this data via their paid API. To do so, visit the Electricity Maps website for [pricing and details](https://www.electricitymaps.com/pricing).
+
+
+## Licenses
+
+The annual grid intensity data is republished from Electricity Maps under the [Open Database License (ODbL)](https://opendatacommons.org/licenses/odbl/summary/). Users of this data through CO2.js must:
+
+- Attribute: Credit Electricity Maps as the source
+- Share-Alike: Keep derivative works under the same license
+- Keep open: Provide unrestricted versions if using DRM
+
+For full details on Electricity Maps methodology see: [https://www.electricitymaps.com/data/methodology](https://www.electricitymaps.com/data/methodology)
+For full detail on the ODbL see: [https://opendatacommons.org/licenses/odbl/summary/](https://opendatacommons.org/licenses/odbl/summary/)

src/docs/co2js/data/marginal-intensity.md

@@ -0,0 +1,36 @@
+---
+title: Data - Marginal intensity
+description: This guide will show you how find and use country-level grid intensity data available in CO2.js.
+eleventyNavigation:
+  key: data-marginal-intensity
+  title: Marginal intensity
+  sectionTitle: Data
+  order: 6.3
+---
+
+# Data - Marginal intensity
+
+You can import annual, country-level marginal grid intensity data from the [UNFCCC](https://unfccc.int/) (United Nations Framework Convention on Climate Change) into your projects directly from CO2.js. For example, if you wanted to use the marginal grid intensity for Australia in a project, then you can do so by using the code below:
+
+```js
+import { marginalIntensity } from '@tgwf/co2/data';
+const { data, type, year } = marginalIntensity;
+
+const { AUS } = data;
+console.log({ AUS })
+```
+
+All countries are represented by their respective [Alpha-3 ISO country code](https://www.iso.org/obp/ui/#search).
+
+### Using CO2.js v0.16 and older
+
+If you are using CO2.js v0.16 or older in your code, then you should import data using the code sample below:
+
+```js
+// Import data from CO2.js
+import { marginalIntensity } from "@tgwf/co2"
+```
+
+## Licenses
+
+The marginal intensity data is published by the Green Web Foundation, under the Creative Commons ShareAlike Attribution Licence ([CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)). ([What does this mean?](https://www.tldrlegal.com/license/creative-commons-attribution-share-alike-cc-sa))

src/docs/co2js/data.md → src/docs/co2js/data/overview.md

@@ -1,15 +1,16 @@
 ---
-title: Data
+title: Data - Overview
 description: This guide will show you how find and use country-level grid intensity data available in CO2.js.
 eleventyNavigation:
-  key: data
-  title: Data
-  order: 5
+  key: data-overview
+  title: Overview
+  sectionTitle: Data
+  order: 6
 ---
 
 # Data
 
-Sourcing carbon intensity data shouldn’t be the remit of developers. For that reason, CO2.js now includes yearly average grid intensity data from [Ember](https://ember-climate.org/data/data-explorer/), as well as marginal intensity data from the [UNFCCC](https://unfccc.int/) (United Nations Framework Convention on Climate Change).
+Sourcing carbon intensity data shouldn’t be the remit of developers. For that reason, CO2.js now includes yearly average grid intensity data from [Electricity Maps](electricitymaps.com), [Ember](https://ember-climate.org/data/data-explorer/), as well as marginal intensity data from the [UNFCCC](https://unfccc.int/) (United Nations Framework Convention on Climate Change).
 
 ## Average and marginal intensity explained
 
@@ -19,40 +20,14 @@ Marginal intensity, on the other hand, looks at where the additional electricity
 
 If you want to learn more about the differences between average or marginal grid intensity data, the team over at Electricity Maps have two great blog posts [explaining both concepts](https://electricitymaps.com/blog/marginal-emissions-what-they-are-and-when-to-use-them/) and why you [might use one over the other](https://electricitymaps.com/blog/marginal-vs-average-real-time-decision-making/).
 
-## Where to find the data
+## Using the data to your projects
 
-The raw data files (in CSV) format, can be found in the `data` folder in the [CO2.js repository](https://github.com/thegreenwebfoundation/co2.js/tree/main/data). We have written a generation script that parses the raw data files, and outputs grid intensity data in unminified JSON and CommonJS formats. The generated output can be found in the `data/output` folder of the CO2.js repository.
-
-## Using emissions intensity data
-
-You can also import annual, country-level marginal or average grid intensity data into your projects directly from CO2.js. For example, if you wanted to use the average grid intensity for Australia in a project, then you can do so by using the code below:
-
-```js
-import { averageIntensity } from '@tgwf/co2/data';
-const { data, type, year } = averageIntensity;
-
-const { AUS } = data;
-console.log({ AUS })
-```
+You can also import annual, country-level marginal or average grid intensity data into your projects directly from CO2.js. For code examples, see the specific pages for the data source you are using:
 
-Likewise, if you want to use annual marginal intensity for Australia:
+- [Electricity Maps](/co2js/data/electricity-maps/)
+- [Ember (average intensity)](/co2js/data/average-intensity/)
+- [UNFCC (marginal intensity)](/co2js/data/marginal-intensity/)
 
-```js
-import { marginalIntensity } from '@tgwf/co2/data';
-const { data, type, year } = marginalIntensity;
+## Where to find the raw data
 
-const { AUS } = data;
-console.log({ AUS })
-```
-
-All countries are represented by their respective [Alpha-3 ISO country code](https://www.iso.org/obp/ui/#search).
-
-### Using CO2.js v0.16 and older
-
-If you are using CO2.js v0.16 or older in your code, then you can import data using the code sample below:
-
-```js
-// Import data from CO2.js
-import { averageIntensity } from "@tgwf/co2"
-import { marginalIntensity } from "@tgwf/co2"
-```
+The raw data files (in CSV) format, can be found in the `data` folder in the [CO2.js repository](https://github.com/thegreenwebfoundation/co2.js/tree/main/data). We have written a generation script that parses the raw data files, and outputs grid intensity data in unminified JSON and CommonJS formats. The generated output can be found in the `data/output` folder of the CO2.js repository.

src/docs/co2js/functions/overview.md

@@ -0,0 +1,18 @@
+---
+title: Functions
+description: This guide will show you how to use the different functions to calculate carbon emissions that are available in CO2.js.
+eleventyNavigation:
+  key: functions-overview
+  title: Overview
+  sectionTitle: Functions
+  order: 5
+---
+
+# Functions
+
+CO2.js exposes four functions that developers can use to return CO2 estimates. This guide will show you how to use the different methods to calculate carbon emissions, and give a brief explanation for each.
+
+- [`perByte`](/co2js/functions/perbyte/)
+- [`perVisit`](/co2js/functions/pervisit/)
+- [`perByteTrace`](/co2js/functions/perbyte-trace/)
+- [`perVisitTrace`](/co2js/functions/pervisit-trace/)

src/docs/co2js/functions/perbyte-trace.md

@@ -0,0 +1,61 @@
+---
+title: Functions - perByteTrace
+description: This guide will show you how to use the perByteTrace function to calculate carbon emissions that are available in CO2.js.
+eleventyNavigation:
+  key: functions-perbyte-trace
+  title: perByteTrace
+  sectionTitle: Functions
+  order: 5.2
+---
+
+# Functions -  perByteTrace <div class="badge badge-warning gap-2 align-middle">Sustainable Web Design Model only</div>
+
+The `perByteTrace()` function is an extension of `perByte()` which allows for certain inputs to be adjusted. This allows for more accurate, scenario specific estimates to be produced using the Sustainable Web Design Model.
+
+<aside class="alert alert-info">
+<p>This function returns a result which includes details of all the variables that were used in the calculation. Since this function allows developers to deviate from the standard Sustainable Web Design Model, we strongly recommend that it is made clear to the end user what values have changed as part of the calculation.</p></aside>
+
+## Accepted parameters
+
+The `perByteTrace()` function accepts the following parameters:
+
+- **bytes** `number` <div class="badge gap-2 align-middle my-0">Required</div>: The value of bytes to estimate emissions for.
+- **green hosting** `boolean` <span class="badge align-middle badge-success my-0">Optional</span>: if the data being measured is served from a green web host.
+- **options**: `object` <span class="badge align-middle badge-success my-0">Optional</span> - A JavaScript object containing any Sustainable Web Design specific variables to be change.
+
+### The `options` parameter
+
+The `options` parameter can contain any of the following keys. These can be used to adjust the values used by the Sustainable Web Design Model's calculation.
+
+- `greenHostingFactor` <div class="badge badge-warning gap-2 align-middle">Sustainable Web Design Model v4 only</div> - A `number` representing the portion of hosting services powered by renewable or zero-carbon energy, between 0 and 1. If the `green hosting` boolean above is set to `true` then the `greenHostingFactor` will always be `1`.
+- `gridIntensity` <span class="badge align-middle badge-success my-0">Optional</span> – an `object` that can contain the following keys:
+  - `device` <span class="badge align-middle badge-success my-0">Optional</span> – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code.
+  - `dataCenter` <span class="badge align-middle badge-success my-0">Optional</span> – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code.
+  - `networks` <span class="badge align-middle badge-success my-0">Optional</span> – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code.
+
+Below is an example which shows both kinds of accepted inputs in use.
+
+```js
+const options = {
+  gridIntensity: {
+    device: 565.629, // Here we have set the grid intensity at the device location using a number.
+    dataCenter: { country: "TWN" }, // Here we have set the data center grid intensity using a country code.
+    networks: 442,
+  },
+};
+```
+
+## Result
+
+The `perByteTrace()` function returns an object with the following keys:
+
+- `co2` - A `number` representing the carbon emissions calculated in grams
+- `green` - A `boolean` indicating whether the calculation was based on data being hosted in a green data center
+- `variables` - An `object`` that details all the other variables used in the calculation. This object will include:
+  - `description` - A static `string` explaining what is being shown.
+  - `bytes` - A `number` showing the bytes that were passed into the function.
+  - `greenHostingFactor` <span class="badge badge-warning gap-2 align-middle">Sustainable Web Design Model v4 only</span> - A `number` representing the portion of hosting services powered by renewable or zero-carbon energy.
+  - `gridIntensity` – an `object` that can contain the following keys:
+    - `device` – A `number` representing the carbon intensity (in grams per kilowatt-hour) used in the calculation.
+    - `dataCenter` – A `number` representing the carbon intensity (in grams per kilowatt-hour) used in the calculation.
+    - `networks` – A `number` representing the carbon intensity (in grams per kilowatt-hour) used in the calculation.

src/docs/co2js/functions/perbyte.md

@@ -0,0 +1,37 @@
+---
+title: Functions - perByte
+description: This guide will show you how to use the perByte function to calculate carbon emissions that are available in CO2.js.
+eleventyNavigation:
+  key: functions-perbyte
+  title: perByte
+  sectionTitle: Functions
+  order: 5.1
+---
+
+# Functions - perByte()
+
+The `perByte()` function can be used with both the [OneByte and Sustainable Web Design Models](/co2js/models/). We recommend using this function, as it will return a CO2 value (in grams) for raw data transfer using a given model. It can be used for calculating emissions from websites, file uploads, streaming etc.
+
+<aside class="alert alert-info">
+<p>If you are using the Sustainable Web Design Model and need to change any of the values used in the calculation, we recommend you use the <a class="text-inherit" href="#perbytetrace-sustainable-web-design-only">perByteTrace function.</a> </p></aside>
+
+```js
+import { co2 } from "@tgwf/co2";
+
+const oneByte = new co2({ model: "1byte" });
+
+const emissions = oneByte.perByte(1000000);
+```
+
+Here we are using the OneByte model, and using the `perByte()` function to check the carbon emissions for transferring 1 million bytes.
+
+## Accepted parameters
+
+The `perByte()` function accepts the following parameters:
+
+- **bytes** `number` <div class="badge gap-2 align-middle my-0">Required</div>: The value of bytes to estimate emissions for.
+- **green hosting** `boolean` <span class="badge align-middle badge-success my-0">Optional</span>: if the data being measured is served from a green web host.
+
+## Result
+
+The `perByte()` function returns a floating point decimal value which is the amount of CO2e (in grams) calculated using the function.