Edgio
Edgio Console

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 Edgio dev server locally:
    Bash
    1edgio 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. Guides are organized by product and version (if applicable).

How to Contribute

You may contribute to our documentation by either:
  • Modifying an existing article. You should edit the Markdown file in the ./guides directory.
  • Creating an article to explain a new concept. You should create a Markdown file in the ./guides directory.
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:
Try the Next.js SSR Example Site
View the Code

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:
Try the Next.js SSR Example Site
View the Code

Templates

Templates are shared content that can be reused across multiple guides. They are located in the src/templates directory. You can include a template in a guide by using the mustache syntax &lcub;&lcub; template&lowbar;name &rcub;&rcub;, where template_name is the name of the template file without the .md extension.
Markdownsrc/templates/sample_template.md
1Content in this template can be shared across multiple guides.
Markdownguides/applications/v7/sample_guide.md
1This guide includes a shared template.
2

3&lcub;&lcub; sample&lowbar;template &rcub;&rcub;

Versioning

This section is only applicable to the Edgio Applications documentation.
All Applications guides are based on the content files within ./guides/applications directory. Guides are organized by version. For example, the getting_started.md guide for the v7 version of the Edgio Applications documentation would be located at ./guides/applications/v7/getting_started.md.
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. This is most common used with shared templates (src/templates).
Markdownsrc/templates/sample_template.md
1Content in this template will be shared across multiple versions of the documentation.
2

3<Condition version="7">
4  Content in this block will only be shown for the v7 version of the guide.
5</Condition>
6

7<Condition version="<=6">
8  Content in this block will be shown for the v6 and earlier versions of the guide.
9</Condition>