Contributing to the Edgio Documentation

Edgio is about empowering developers and our documentation is no different. We welcome feedback whether it consists of fixing a typo or a better explanation. You can find the source code for this documentation site in a public GitHub repository. Once you have made the desired changes, submit a pull request. Alternatively, you can let us know how we can improve the documentation by filing an issue.

Running the Documentation Site Locally #

Run our documentation site on your local machine through the following steps:

1. Clone the Github repository:

   Bash

   Copy

   1git clone git@github.com:edgio-docs/edgio-docs.git

2. Install the dependencies:

   Bash

   Copy

   1cd edgio-docs
   2yarn install

3. Start the Next.js dev server locally:

   Bash

   Copy

   1yarn dev

Once you have performed the above steps, you will be able to view a local instance of the documentation site in your browser at http://127.0.0.1:3000.

Architecture #

Edgio documentation is a Next.js application running on Edgio. Each article is a Markdown file located in the guides folder.

How to Contribute #

You may contribute to our documentation by either:

• Modifying an existing article.

  Use the src/data/SidebarMenuItems.tsx file to locate the corresponding Markdown file.

• Creating an article to explain a new concept. You should create a Markdown file in the guides folder and add a reference to it in src/data/SidebarMenuItems.tsx.

We recommend the following process for submitting a change:

1. Clone the repo and make sure you can run the documentation site locally.
2. Make your amazing edit — even a typo fix is an amazing edit!
3. Commit and push your change branch to the origin repository.
4. Submit a pull request back to the Edgio documentation repository (to the main branch).

Formatting #

Use standard Markdown syntax when formatting content. Follow these guidelines when formatting content:

• Apply bold formatting to all UI elements.

• Apply bold formatting to labels. A label describes the content that follows it. The two basic types of labels are explained below.

  • Paragraph: This type of label is a paragraph that solely consists of the label (e.g., Syntax: or Example:).
  • List Item: This type of label appears at the start of a list item. For example, notice how this list item has been formatted.

• Enclose the following type of content with a pair of backticks: HTTP status codes, cache status codes, headers, sample configurations, sample values, code elements, and API properties.

  Example:

  A successful request returns a 200 OK.

• Capitalize placeholder values and enclose them within angle brackets. A placeholder is a word or phrase that represents a value.

  Example:

  Add a CNAME DNS entry whose value is set to _acme-challenge.<DOMAIN>.

Callout #

Add a callout to bring attention to a specific part of the guide.

1// set type to: 'info' | 'tip' | 'important' | 'warning' | 'danger';
2
3<Callout type="info">
4
5  A note provides additional information.
6
7</Callout>
8
9<Callout type="tip">
10
11  A tip describes a best practice or provides advice.
12
13</Callout>
14
15<Callout type="important">
16
17  An important note provides essential information.
18
19</Callout>
20
21<Callout type="warning">
22
23  A warning provides cautionary information about a potential pitfall.
24
25</Callout>
26
27<Callout type="danger">
28
29  Identifies a configuration or action that can negatively impact your site's performance or behavior.
30
31</Callout>

The above code renders:

Fenced Code Block #

Fence code excerpts with triple backticks. If the code is language-specific, then you should indicate that language by appending it to the starting triple backticks (e.g., ```html or ```bash).

1// This codeblock has the 'js' language module (with JS comment)
2console.log(new Date());

1<button type="button" class="btn btn-primary">Primary</button>

1# This codeblock has the 'bash' language module (with Bash comment)
2echo "Hello World"

1// This codeblock has not been assigned a language module
2upload.build.layer0.co
3app.layer0.co

You may highlight various lines of code by specifying line number ranges within ins="", del="", or highlight="", where the value inside "" can be "1,2,3,8,9,10" or "1-3,8-10", for example.

1new Router()
2  .get('/pages/c/:categoryId', ({cache}) => {
3    cache({
4      browser: {
5        maxAgeSeconds: 0,
6        serviceWorkerSeconds: 60 * 60 * 24,
7      },
8      edge: {
9        maxAgeSeconds: 60 * 60 * 24,
10        staleWhileRevalidateSeconds: 60 * 60,
11      },
12    });
13  })
14  .fallback(({renderWithApp}) => renderWithApp());

To highlight lines based on a diff, mark lines with a leading +/- and specify the diff attribute such as: ```js diff

1new Router()
2  .get('/pages/c/:categoryId', ({ cache }) => {
3    cache({
4      browser: {
5        maxAgeSeconds: 0,
6        serviceWorkerSeconds: 60 * 60 * 24,
7      },
8      edge: {
9        maxAgeSeconds: 60 * 60 * 24,
10        staleWhileRevalidateSeconds: 60 * 60,
11      },
12    })
13  })
14  .fallback(({ renderWithApp }) => renderWithApp())

Video #

1<Video src="video src url" />

Button Link #

1/*
2interface IButtonLinkProps {
3 variant: 'fill' | 'stroke';
4 type: 'default' | 'code' | 'deploy';
5 children: React.ReactNode;
6 href: string | UrlObject;
7 withIcon: boolean;
8}
9*/
10
11
12<ButtonLink variant="fill" type="default" href="...">
13 Try the Next.js SSR Example Site
14</ButtonLink>
15<ButtonLink variant="stroke" type="code" withIcon={true} href="...">
16 View the Code
17</ButtonLink>
18<ButtonLink variant="stroke" type="deploy" withIcon={true} href="..." />

Renders:

Button Links Group #

1<ButtonLinksGroup>
2  <ButtonLink variant="fill" type="default" href="...">
3    Try the Next.js SSR Example Site
4  </ButtonLink>
5  <ButtonLink variant="stroke" type="code" withIcon={true} href="...">
6    View the Code
7  </ButtonLink>
8  <ButtonLink variant="stroke" type="deploy" withIcon={true} href="..." />
9</ButtonLinksGroup>

Renders:

Versioning#

All documentation guides are based on the content files within src/guides/. All paths under this directory, with the exception of src/guides/v*/, are assumed to represent the most current Edgio version.

Assume the current version of Edgio is v6, the guide src/guides/nextjs.md

If you need to create a new version of a guide, you can create a new directory under src/guides/ with the version number as the directory name. For example, if you wanted to create a version of the src/guides/getting_started.md guide, you would create a new directory src/guides/v6/getting_started.md and copy the nextjs.md file into that directory. The new version of the guide would be available at /guides/v6/getting_started.

This approach allows us to maintain multiple versions of a guide that may differ significantly from a previous version, while still maintaining a single source of truth for the most current version of the guide.

If a guide has minor changes between versions, you can conditionally render content based on the current version of the documentation being browsed. For example, if you wanted to render a different message for the v6 version of the guide, you could use the <Condition version="..." /> component:

1---
2title: Contributing
3---
4
5<Condition version="5">
6  This will only show for requests to `/guides/v5/contributing`.
7</Condition>
8
9<Condition version="6">
10  This will only show for requests to `/guides/v6/contributing` or `/guides/contributing`.
11</Condition>
12
13<Condition version=">=5">
14  This will only show for requests to:
15    - `/guides/contributing` (current v6 version)
16    - `/guides/v5/contributing`
17    - `/guides/v6/contributing`
18</Condition>

Try it out:

/guides/contributing | /guides/v5/contributing |/guides/v6/contributing

This will only show for requests to:

• /guides/contributing (current v6 version)
  
• /guides/v5/contributing
  
• /guides/v6/contributing