You are reading Edgio v6 docs. Check out our latest docs for Edgio v7.
Edgio
Edgio

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
    1git clone git@github.com:edgio-docs/edgio-docs.git
  2. Install the dependencies:

    Bash
    1cd edgio-docs
    2yarn install
  3. Start the Next.js dev server locally:

    Bash
    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).

For more details, the Pro Git book has a helpful contributing guide that walks you through the process of submitting a pull request to an open source repository on GitHub.


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.

TypeScript
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:

A note provides additional information.

A tip describes a best practice or provides advice.

An important note provides essential information.

A warning provides cautionary information about a potential pitfall.

Identifies a configuration or action that can negatively impact your site’s performance or behavior.


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).

JavaScript
1// This codeblock has the 'js' language module (with JS comment)
2console.log(new Date());
HTML
1<button type="button" class="btn btn-primary">Primary</button>
Bash
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.

JavaScript
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

JavaScript
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

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

Button Link

TypeScript
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

TypeScript
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:

Markdownsrc/guides/contributing.md
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/v6/contributing or /guides/contributing.

This will only show for requests to:

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