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 layer0-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. Fork the Edgio documentation repository on GitHub.
  2. Clone the repo and make sure you can run the documentation site locally.
  3. Make your amazing edit — even a typo fix is an amazing edit!
  4. Commit and push your change back to your fork on GitHub.
  5. 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<!-- This codeblock has the 'html' language module (with HTML comment) -->
2<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 // Prevent search engine bot(s) from indexing
3 // Read more on: https://docs.edg.io/guides/cookbook#blocking-search-engine-crawlers
4 .noIndexPermalink()
5 .get('/pages/c/:categoryId', ({ cache }) => {
6 cache({
7 browser: {
8 maxAgeSeconds: 0,
9 serviceWorkerSeconds: 60 * 60 * 24,
10 },
11 edge: {
12 maxAgeSeconds: 60 * 60 * 24,
13 staleWhileRevalidateSeconds: 60 * 60,
14 },
15 })
16 })
17 .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 // Prevent search engine bot(s) from indexing
3 // Read more on: https://docs.edg.io/guides/cookbook#blocking-search-engine-crawlers
4 .noIndexPermalink()
5 .get('/pages/c/:categoryId', ({ cache }) => {
6 cache({
7 browser: {
8 maxAgeSeconds: 0,
9 serviceWorkerSeconds: 60 * 60 * 24,
10 },
11 edge: {
12 maxAgeSeconds: 60 * 60 * 24,
13 staleWhileRevalidateSeconds: 60 * 60,
14 },
15 })
16 })
17 .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: