graphql-engine/docs/wiki/docusaurus-mdx-guide/list-tables.mdx

---
sidebar_position: 10
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CodeBlock from '@theme/CodeBlock';
import Link from '@docusaurus/Link';

# List Tables

Tables are the only complex stuff in markdown.

## Docusaurus - MDX

If the table consists of simple text and no complex UI and no column width control. This can be plain markdown syntax as below:

```markdown
| Field             | Description                                                                                                                                                                                                                                                                                                                                                                              |
|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Region            | The region of the datacentre where your New Relic account stores its data. [Read more about regions on New Relic docs.](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/our-eu-us-region-data-centers)                                                                                                                                                      |
| API Key           | API keys are unique to your organization. An API key is required by the New Relic API to submit metrics and events to New Relic. You can get the API key from [here](https://one.newrelic.com/launcher/api-keys-ui.api-keys-launcher) if you are in New Relic US region and [here](https://one.eu.newrelic.com/launcher/api-keys-ui.api-keys-launcher) if you're in New Relic EU region. |
| Host              | The name of the originating host of the log and metrics.                                                                                                                                                                                                                                                                                                                                 |
| Custom Attributes | Custom Attributes associated with your logs and metrics. A default source tag `hasura-cloud-metrics` is added to all exported logs and metrics. Attributes `project_id` and `project_name` are added to all exported metrics.                                                                                                                                                            |
| Service Name      | The name of the application or service generating the log events.                                                                                                                                                                                                                                                                                                                        |
```

Unfortunately, `markdown` doesn't have straightforward syntax to control the width and had to rely on html for this.

```html {4,5}
<table>
  <thead>
    <tr>
      <th width="20%">Field</th>
      <th width="40%">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Region</td>
      <td>The region of the datacentre where your New Relic account stores its data. <Link to="https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/our-eu-us-region-data-centers">Read more about regions on New Relic docs.</Link></td>
    </tr>
    <tr>
      <td>API Key</td>
      <td>API keys are unique to your organization. An API key is required by the New Relic API to submit metrics and events to New Relic. You can get the API key from <Link to="https://one.newrelic.com/launcher/api-keys-ui.api-keys-launcher">here</Link> if you are in New Relic US region and <Link to="https://one.eu.newrelic.com/launcher/api-keys-ui.api-keys-launcher">here</Link> if you're in New Relic EU region.</td>
    </tr>
    <tr>
      <td>Host</td>
      <td>The name of the originating host of the log and metrics.</td>
    </tr>
    <tr>
      <td>Custom Attributes</td>
      <td>Custom Attributes associated with your logs and metrics. A default source tag <code>hasura-cloud-metrics</code> is added to all exported logs and metrics. Attributes <code>project_id</code> and <code>project_name</code> are added to all exported metrics.</td>
    </tr>
    <tr>
      <td>Service Name</td>
      <td>The name of the application or service generating the log events.</td>
    </tr>
  </tbody>
</table>
```

:::tip Few things to note:

If a table cell is mixed with text and markdown elements (`code highlighters`, [links](/docusaurus-mdx-guide/links.mdx)
etc., Please prefer `html` syntax over markdown as markdown won't be parsed correctly.

```html
<!-- Usage of <Link> for `[link](https://...)` -->
<tr>
  <td>Region</td>
  // highlight-next-line
  <td>The ... data. <Link to="https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/our-eu-us-region-data-centers">Read ... docs.</Link></td>
</tr>

<!-- Usage of <code> for `code` -->
<tr>
  <td>Custom Attributes</td>
  // highlight-next-line
  <td>Custom ... tag <code>hasura-cloud-metrics</code> is ... Attributes <code>project_id</code> and <code>project_name</code> are ... metrics.</td>
</tr>
```

:::

Which would render like this

<table>
  <thead>
    <tr>
      <th width="20%">Field</th>
      <th width="40%">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Region</td>
      <td>The region of the datacentre where your New Relic account stores its data. <Link to="https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/our-eu-us-region-data-centers">Read more about regions on New Relic docs.</Link></td>
    </tr>
    <tr>
      <td>API Key</td>
      <td>API keys are unique to your organization. An API key is required by the New Relic API to submit metrics and events to New Relic. You can get the API key from <Link to="https://one.newrelic.com/launcher/api-keys-ui.api-keys-launcher">here</Link> if you are in New Relic US region and <Link to="https://one.eu.newrelic.com/launcher/api-keys-ui.api-keys-launcher">here</Link> if you're in New Relic EU region.</td>
    </tr>
    <tr>
      <td>Host</td>
      <td>The name of the originating host of the log and metrics.</td>
    </tr>
    <tr>
      <td>Custom Attributes</td>
      <td>Custom Attributes associated with your logs and metrics. A default source tag <code>hasura-cloud-metrics</code> is added to all exported logs and metrics. Attributes <code>project_id</code> and <code>project_name</code> are added to all exported metrics.</td>
    </tr>
    <tr>
      <td>Service Name</td>
      <td>The name of the application or service generating the log events.</td>
    </tr>
  </tbody>
</table>

## With Code Blocks

When a table cell is just a codeblock, the normal triple tick syntax works fine. But, please do leave an intentional empty line before and after the code block.
Also, start the code block and respective cell (`td/th`) at the very beginning of line (no empty tabs/spaces at start).

```html
    <table>
      <thead>
        <tr>
          <th width="20%">Field</th>
          <th width="40%">Query</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td><code>query</code></td>
    <td>

    ```graphql
      query MyQuery {
        ...
      }
    ```

    </td>
        </tr>
      </tbody>
    </table>
```

Do one better and ignore the indentation altogether for all tags in table. This might be bit of not so eye-friendly to read, but works.
Please do not that this is required only when there is a cell involving code block.

<table>
  <thead>
    <tr>
      <th width="20%">Field</th>
      <th width="40%">Query</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>query</code></td>
<td>

```graphql
  query MyQuery {
    ...
  }
```

</td>
    </tr>
  </tbody>
</table>


The `:widths:` can be added as `width` attribute to `html` - `th`. And the `:header-rows:` determines the number of
header rows to be considered for `<thead>`.

```html {2-8}
    <table>
    <thead>
      <tr>
        <th width="10%">Status code</th>
        <th width="10%">Description</th>
        <th width="30%">Response Structure</th>
      </tr>
    </thead>
    <tbody>
    <tr>
    <td><code>200</code></td>
    <td>Success</td>
    <td>

    ```
    Request Specific
    ```

    </td>
    </tr>
    <tr>
    <td><code>400</code></td>
    <td>Bad Request</td>
    <td>

    ```haskell
    {
        "path"  : String,
        "error" : String
    }
    ```

    </td>
    </tr>
    <tr>
    <td><code>401</code></td>
    <td>Unauthorized</td>
    <td>

    ```haskell
    {
        "error" : String
    }
    ```

    </td>
    </tr>
    <tr>
    <td><code>500</code></td>
    <td>Internal server error</td>
    <td>

    ```haskell
    {
        "error" : String
    }
    ```

    </td>
    </tr>
    </tbody>
    </table>
```

<table>
<thead>
  <tr>
    <th width="10%">Status code</th>
    <th width="10%">Description</th>
    <th width="30%">Response Structure</th>
  </tr>
</thead>
<tbody>
<tr>
<td><code>200</code></td>
<td>Success</td>
<td>

```
Request Specific
```

</td>
</tr>
<tr>
<td><code>400</code></td>
<td>Bad Request</td>
<td>

```haskell
{
    "path"  : String,
    "error" : String
}
```

</td>
</tr>
<tr>
<td><code>401</code></td>
<td>Unauthorized</td>
<td>

```haskell
{
    "error" : String
}
```

</td>
</tr>
<tr>
<td><code>500</code></td>
<td>Internal server error</td>
<td>

```haskell
{
    "error" : String
}
```

</td>
</tr>
</tbody>
</table>