Content style guide and reference

Follow these style conventions and guidelines when authoring content in Docusaurus:

Files and directories

Naming

Files

Omit articles.
Omit pronouns.
Omit single quotation marks and other special characters.
Omit coordinating conjunctions and prepositions if they add no clarity or other value.
Omit add-on or platform name if already visible in the preceding file path.
Use a single hyphen (-) as the word separator.
Use lower case.
Use the mdx extension for all Markdown files.
For a docs page, as a rule, name the page file based on the page title (<h1>).
For a docs parent page, name the file index.mdx.

# Docs page file
connect-to-ollama-from-excel-and-word.mdx

# Docs directory and parent page file
docs/ai-models/index.mdx

# Image file
set-llm-server-url-ollama.png

Directories

Omit articles.
Omit pronouns.
Omit single quotation marks and other special characters.
Omit coordinating conjunctions and prepositions if they add no clarity or other value.
Omit add-on or platform name if already visible in the preceding file path.
Use a single hyphen (-) as the word separator.
Use lower case. Except for component directories, which use the component name casing.

# Docs directory
docs/ai-models

# Docs directory and index file (parent page file)
docs/ai-models/index.mdx

# Component directory
src/components/Video

Structure

Docs

Place a parent page in the root of the directory for the section whose parent the page is. (The parent page file is the index file for the directory.)
```
docs/ai-models/index.mdx
```

Place a child page file and its parent page file in the same directory.

docs/ai-models/connect-to-ollama-from-excel-and-word.mdx
docs/ai-models/index.mdx
docs/ai-models/set-and-manage-api-keys.mdx

Images

Place all images for docs in the appropriate subdirectory in static/.
```
static/images/docs/llm-servers/set-llm-server-url-ollama.png
```

Content (MDX & JSX)

tip

For a doc that follows these guidelines, see the Content reference:

Page: YAMM Help site
Source code: GitHub

Basics

Add an empty line after each line of content, including inside lists and JSX table cells.

Use bulk AI tools if:

- You want AI responses saved as plain text in cells.

- You want better tracking information about the progress of AI requests.

- You do not want to write formulas.

Inside JSX table cells, do not add an empty line after the last line in a cell element (<th> or <td>).

<td>
  None.

  Use the default model or select a different model.
</td>

Add an empty line at the end of each file.
Indent with spaces. Use 2-space indentation (unless parent element alignment dictates otherwise). Never indent with tabs.
Use single quotation marks for string values in JavaScript and JSX. Note that this also includes code that looks like HTML (which is actually JSX).
```
import Launch from '@site/docs/_reuse-library/generic/_launch.mdx';

<Launch app='Sheets' />
```
In void elements, always add a space before the ending />, unless the ending is on its own line, in which case follow normal indentation conventions.
```
<InstallButtons />

<Launch app='Sheets' />
```
Never use   for anything. For example, if you need to add vertical space between elements, use the appropriate block-level element or update the site CSS.
If a JSX element takes multiple attributes, split each attribute into its own line.
```
<Intro
 app={app}
 platform={platform}
 prompts={prompts}
 rows={rows}
/>
```
If a JSX element takes a single attribute or two attributes that together take up only a short space, keep the opening tag on a single line.
```
<Launch app='Sheets' />

<TabItem label={<TabLabel value='sheets' />} value='sheets'>
```

Code blocks

Use the triple backtick (```) for code blocks. Keep the opening and closing triple backticks on their own lines.

```bash
# Mac with an Apple silicon processor
cd /opt/homebrew/etc/nginx

# Mac with an Intel processor
cd /usr/local/etc/nginx
```

If possible, always define the language for a code block.

# Supported languages (default)

actionscript
c
clike
coffeescript | coffee
cpp
css
flow
go
graphql
javadoclike
javascript | js
jsdoc
json | webmanifest
jsx
kotlin | kt | kts
markdown | md
markup | html | xml
n4js | n4jsd
objectivec | objc
plain | plaintext | text | txt
python | py
reason
regex
rust
sql
swift
tsx
typescript | ts
yaml | yml

# Additional supported languages (docusaurus.config.js)

bash | shell | sh
git
http
nginx
powershell
properties
regex
systemd

For more information about what languages Docusaurus supports by default and what languages it can be configured to support, see the Docusaurus documentation.

If you want to render a code block without the copy button, use the language buttonless. Note that the buttonless code block will not include any syntax highlighting.
```
```buttonless
GPT(prompt, [value], [temperature], [model])
```
```

Align the code to the triple backticks.

export const getNginxConfig = (server) => {
  if (server === 'LM Studio') {
    return <NginxConfigLmStudio />;
  } else if (server === 'Ollama') {
    return <NginxConfigOllama />;
  } else {
    return 'ERROR';
  }
};

If you need to define a title for a code block, use title="My title" after the language definition (separated by a single space).
```
```bash title="Mac with an Apple silicon processor"
cd /opt/homebrew/etc/nginx
```
```

Collapsibles

Create a collapsible content section with the <Collapsible> custom component. Use 2-space indentation.

// Collapsible with a heading

<Collapsible
  heading='My heading'
  headingId='my-heading'
  headingLevel={2}
  defaultOpen={false}
>
  My collapsible content...
</Collapsible>

// Collapsible with a body text label

<Collapsible
  labelClosed='Click to open...'
  labelOpened='Click to close...'
  defaultOpen={false}
>
  My collapsible content...
</Collapsible>

For more information about using the component, see the source code comment.

To create a prerequisites collapsible, use the _details-component.mdx partial. The collapsible renders open by default.

import Prerequisites from '@site/docs/_reuse-library/generic/_details-component.mdx';

<Prerequisites
  title='Prerequisites'
  prereqlist={
    <p>You are the owner or an admin of the space.</p>
  }
/>

If you want to render the prerequisites collapsible closed by default, set the open={false} prop for the partial.

<Prerequisites
  title='Prerequisites'
  open={false}
  prereqlist={
    <p>You are the owner or an admin of the space.</p>
  }
/>

Formatting

Use the double asterisk (**) for bold.
```
**bold text**
```
Use the underscore (_) for italics.
```
_italicized text_
```
Use the backtick (`) for monospace.
```
`monospaced text`
```
Use the double tilde (~~) for strikethrough.
```
~~stricken text~~
```

Front matter

Define the following front matter for every doc:
- title: Document title (metadata). For SEO purposes, keep the title under 30 or so characters (since Docusaurus automatically appends the title with the site meta title defined in docusaurus.config.js). Docusaurus automatically uses the document title (without the site meta title) as the L1 heading for the page if you do not separately define an L1 heading.
- sidebar_label: Sidebar title for the page. Define this only if you need a shorter text in the sidebar than on the page.
- description: Page meta description. For SEO purposes, aim for 70-155 characters, but you can go up to 300 characters if needed. As a rule, use the first sentence or paragraph of the page as the meta description, or at least keep the two as consistent as possible.
```
---
title: Overview of GPT for Excel
sidebar_label: Overview
description: GPT for Excel is a Microsoft Excel add-in that integrates the power and intelligence of generative AIs directly into the Excel user interface.
---
```

Never define a label for a doc item in sidebars.js. Use the title front matter in the doc instead.

✅ Correct (REPLACE)

{
  type: 'doc',
  id: 'sign-in/sign-in-with-microsoft-or-google',
},

❌ Incorrect (REPLACE)

{
  type: 'doc',
  label: 'Sign in with Microsoft or Google',
  id: 'sign-in/sign-in-with-microsoft-or-google',
},

Headings

Start every doc with the title front matter field. Docusaurus automatically uses the field as the L1 heading for the page.
```
---
title: Overview of GPT for Excel
---
```

Use L2 and lower for all headings after the page title.

---
title: Overview of GPT for Excel
---

## Use cases

## Features

### Bulk tools

### GPT functions

### Formula assistant

## Benefits

## What's next

Use L2 through L4 for body text headings.
```
## Heading 1

### Heading 2

#### Heading 3
```
Do not use L5 or lower, as a rule.
If you need to manually define a heading ID, use \{#custom-id} after the heading (separated by a single space). The backward slash is required to escape the opening curly brace so that Docusaurus does not parse the ID as a JavaScript expression.
```
## Create API keys \{#create}
```
As a rule, do not define custom heading IDs. The only exceptions, where you should define custom heading IDs, are:
- FAQs
- Troubleshooting entries
These are referenced from outside the site and need to have stable anchors.

Images

For SEO and accessibility purposes, always define alt text for an image. Unless the image is purely decorative, in which case skip alt text.
Do not reference external images. Use only internal images saved in static/.

Block-level images

Use the <Figure> custom component for block-level images. Always define the path prop and, unless the image is purely decorative, the description prop.
```
<Figure
 path='getting-started/first-mail-merge/installation-complete-how-to-launch-yamm-1.png'
 description='Google Sheets with YAMM sidebar open'
/>
```
You can also define the following optional props for a <Figure>:
- width: Custom image width. Can be a number ({800}), numeric string ('800'), or CSS string ('800px', '80%', '32rem'). Use a number for consistency.
- border: If true, renders a border around the image. Defaults to true.
- caption: If true, renders the description as a caption for the image. Defaults to false.
- disableZoomOverlay: If true, disables desktop zoom overlay and hover hint. Defaults to false.
```
<Figure
 path='getting-started/first-mail-merge/installation-complete-how-to-launch-yamm-2.png'
 description='YAMM add-on sidebar in Google Sheets'
 width={800}
/>

<Figure
 path='getting-started/first-mail-merge/send-first-mail-merge-with-yamm-1.png'
 description='YAMM mail merge step 1'
 border={false}
/>
```
Start the image file path from static/images/docs/.
```
# File: static/images/docs/gpt-for-docs/api-key-origin-space.png

gpt-for-docs/api-key-origin-space.png
```
For more information, see the component source code in GitHub.

JSX

Wrap JavaScript expressions inside curly braces {...}.

You've successfully dipped your toe in GPT for {props.app}. 💚

Do not write lines with JavaScript expressions as JSX (“HTML”). Write them as regular Markdown.
✅ Correct (REPLACE)
In the sidebar menu, select **{app[props.app].menuItem}**.
❌ Incorrect (REPLACE)
In the sidebar menu, select {app[props.app].menuItem}.

Interleave JSX and Markdown so that you use as few JSX elements as possible. Use a JSX element only when there’s no appropriate Markdown equivalent.

✅ Correct (REPLACE)

- Learn more about <Link to={`/gpt-for-${props.app.toLowerCase()}/overview`}>GPT for {props.app}</Link>.

- Get going with <Link to={`/gpt-for-${props.app.toLowerCase()}/bulk-ai-tools`}>bulk AI tools</Link>.

- Get going with <Link to={`/gpt-for-${props.app.toLowerCase()}/gpt-functions/start-using-gpt-functions`}>GPT functions</Link>.

- Try out different [AI models](/ai-models/index.mdx).

- Try out example use cases for different [business applications](/use-cases-spreadsheets/business-applications.mdx) and [product capabilities](/use-cases-spreadsheets/product-capabilities.mdx).

❌ Incorrect (REPLACE)

<ul>
  <li>
    <p>Learn more about <Link to={`/gpt-for-${props.app.toLowerCase()}/overview`}>GPT for {props.app}</Link>.</p>
  </li>
  <li>
    <p>Get going with <Link to={`/gpt-for-${props.app.toLowerCase()}/bulk-ai-tools`}>bulk AI tools</Link>.</p>
  </li>
  <li>
    <p>Get going with <Link to={`/gpt-for-${props.app.toLowerCase()}/gpt-functions/start-using-gpt-functions`}>GPT functions</Link>.</p>
  </li>
  <li>
    <p>Try out different <Link to='/ai-models'>AI models</Link>.</p>
  </li>
  <li>
    <p>Try out example use cases for different <Link to='/use-cases-spreadsheets/business-applications'>business applications</Link> and <Link to='/use-cases-spreadsheets/product-capabilities'>product capabilities</Link>.</p>
  </li>
</ul>

Inline images

In MDX content, use ![alt text](/path-to-image/image-name.png) for inline images.
```
![Microsoft logo](/images/global/icon-microsoft-excel.svg)
```

In JSX content, use the <img> element for inline images.

import useBaseUrl from '@docusaurus/useBaseUrl';

<img src={useBaseUrl('/images/global/icon-microsoft-excel.svg')} alt='Microsoft logo' />

Start the image file path from static.

# File: static/images/global/icon-microsoft-excel.svg

/images/global/icon-microsoft-excel.svg

Links

Internal links in MDX

As a rule, use file paths for internal doc page links. File paths always use the full file name, including the extension.
```
[Quickstart for spreadsheets](/quickstart-for-spreadsheets.mdx)
```
If a file path does not work, use a URL path instead (simply omit the file extension).
```
[Quickstart for spreadsheets](/quickstart-for-spreadsheets)
```

When linking to another doc that is in the same directory or in a direct subdirectory, use a relative path. Relative paths never start with /.

# Target doc in the same directory
[Search the web](search-web.mdx)

# Target doc in a subdirectory of the current directory
[Create GPT formulas](gpt-functions/create-gpt-formulas/index.mdx)

Otherwise, use an absolute path, including when linking to a root-level doc. Absolute paths start with /.

# Root-level doc
[Quickstart for spreadsheets](/quickstart-for-spreadsheets.mdx)

# Target doc in an adjacent directory
[Scrape the web from Google Sheets](/gpt-for-sheets/scrape-web.mdx)

Internal links in JSX

Use the <Link> component for internal links inside JSX content where Markdown links are not an option.
```
<Link to='/quickstart-for-spreadsheets'>Quickstart for spreadsheets</Link>
```

When linking to another doc that is in the same directory or in a direct subdirectory, use a relative path. Relative paths never start with /.

# Target doc in the same directory
<Link to='search-web'>Search the web</Link>

# Target doc in a subdirectory of the current directory
<Link to='gpt-functions/create-gpt-formulas'>Create GPT formulas</Link>

Otherwise, use an absolute path, including when linking to a root-level doc. Absolute paths start with /.

# Root-level doc
<Link to='/quickstart-for-spreadsheets'>Quickstart for spreadsheets</Link>

# Target doc in an adjacent directory
<Link to='/gpt-for-sheets/scrape-web'>Scrape the web from Google Sheets</Link>

If you’re linking to another doc from an index.mdx page, always use an absolute path. (Relative paths do not work on index pages on sites that have trailing slashes in URLs disabled.)

# Target doc in the same directory as the index.mdx
<Link to='/gpt-for-excel/search-web'>Search the web</Link>

# Target doc in a subdirectory of the current directory with the index.mdx
<Link to='/gpt-for-excel/gpt-functions/create-gpt-formulas'>Create GPT formulas</Link>

External links

In MDX content, use a regular Markdown link.
```
[Docusaurus](https://docusaurus.io/)
```

In JSX content, use the <Link> component.

<Link to='https://docusaurus.io/'>Docusaurus</Link>

Lists

For unordered list items, use the hyphen (-) followed by a single space.

Use bulk AI tools if:

- You want AI responses saved as plain text in cells.

- You want better tracking information about the progress of AI requests.

- You do not want to write formulas.

For ordered list items, use the number 1 followed by a period and a single space. Do not use running numbering.

Bulk tools automatically skip:

The header row

Rows with content in the result column

Rows where all input columns are empty

Hidden or filtered rows

Indent child lists to align with the text of the parent item.

Choose the method that best fits your needs:

- Use bulk AI tools if:

  - You want AI responses saved as plain text in cells.

  - You want better tracking information about the progress of AI requests.

  - You do not want to write formulas.

- Use GPT functions if:

Indent nested content to align with the text of the parent item.

1. In the sidebar, select **Bulk AI tools** and click **Prompt images (Vision)**.

   <Figure
     path='getting-started/first-mail-merge/send-first-mail-merge-with-yamm-2.png'
     description='YAMM sidebar showing campaign options'
   />

Tables

Use JSX tables whenever possible.

JSX tables

Use the following basic table structure.

<table>
  <thead>
    <tr>
      <th>Header</th>
      <th>Header</th>
      <th>Header</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        Content
      </td>
      <td>
        Content
      </td>
      <td>
        Content
      </td>
    </tr>
  </tbody>
</table>

In a <th> element, keep the element tags and the element content on the same line. (The element content should not take up multiple lines.) Do not use JSX in the content.
```
<th>Setup</th>
```
In a <td> element, separate the element tags and the element content into different lines, even when you only have a single line of content. Use regular Markdown in the content. Use JSX only if you need to add a custom component, such as <Figure>. Add an empty line after each line of content, except the last one.
```
<td>
 None.

 Use the default model or select a different model.
</td>
```

Use 2-space indentation.

<table>
  <thead>
    <tr>
      <th>Use</th>
      <th>Setup</th>
      <th>When</th>
      <th>Available for</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        **Models without an API key**
      </td>

To align text in a <th> or <td> element, add one of the following attributes to the element opening tag.
- style={{ textAlign: 'left' }} (default for <td>)
- style={{ textAlign: 'right' }}
- style={{ textAlign: 'center' }} (default for <th>)
- style={{ textAlign: 'justify' }}
```
<td style={{ textAlign: 'center' }}>
 X
</td>
```

To manually set the width of columns, use the <colgroup> element. Define the widths as percentages that total 100%.

<table>
  <colgroup>
    <col style={{ width: '20.00%' }} />
    <col style={{ width: '30.00%' }} />
    <col style={{ width: '30.00%' }} />
    <col style={{ width: '20.00%' }} />
  </colgroup>
  <thead>
    <tr>
      Use

To create a named anchor for a table row, add id='anchor-name' to the <tr> element opening tag.
```
<tr id='ollama'>
 <td>
 **Ollama models:**
```

React JavaScript

Basics

Use 2-space indentation.

function validatePath(path) {
  if (typeof path !== 'string' || path.trim() === '') {
    console.error('[Video] `path` must be a non-empty string.');
    return false;
  }
  if (path.startsWith('/')) {
    console.error('[Video] `path` must not start with a forward slash.');
    return false;
  }
  return true;
}

Use single quotation marks for string values in JavaScript.

const BUTTON_CONFIG = {
  Google: {
    label: 'Install GPT for Sheets and Docs',
    logo: 'img/google-logo.svg',
  },
  Microsoft: {
    label: 'Install GPT for Excel and Word',
    logo: 'img/microsoft-logo.svg',
  },
};

Use single quotation marks for string values in JSX.

export default function InstallButtons() {
  return (
    <div className={styles.installButtons}>
      <InstallButton platform='Google' />
      <InstallButton platform='Microsoft' />
    </div>
  );
}

Files and directories​

Naming​

Files​

Directories​

Structure​

Docs​

Images​

Content (MDX & JSX)​

Basics​

Code blocks​

Collapsibles​

Formatting​

Front matter​

Headings​

Images​

Block-level images​

JSX​

Inline images​

Links​

Internal links in MDX​

Internal links in JSX​

External links​

Lists​

Tables​

JSX tables​

React JavaScript​

Basics​

Files and directories

Naming

Files

Directories

Structure

Docs

Images

Content (MDX & JSX)

Basics

Code blocks

Collapsibles

Formatting

Front matter

Headings

Images

Block-level images

JSX

Inline images

Links

Internal links in MDX

Internal links in JSX

External links

Lists

Tables

JSX tables

React JavaScript

Basics