Markdown writing guide

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

This guide has basic information on how to write in MDX-compatible Markdown syntax. It is not intended to be exhaustive. Read the Docusaurus Markdown features, Basic Markdown Syntax, and Extended Syntax for more details and examples.

File format and naming convention

When creating new files, keep the filename short. Don't use capital letters or spaces. When the filename of a Markdown file matches the name of a folder exactly, clicking the folder displays the contents of the Markdown file.

A Markdown file can have either an .md or .mdx extension but you can override the MD format with the front matter format: mdx. When choosing between the MD and MDX formats, use the MDX format only if you are using JSX. The MDX format is strict, and you may get compilation errors.

By default, documents and folders displayed on the left sidebar are sorted alphabetically. You can specify custom labels and order:

For documents, use the sidebar_position and sidebar_label front matter:
```
sidebar_position: 1
sidebar_label: 'Custom document title'
```
For folders, create a _category_.yml file within a folder and specify the position and label front matter in that file:
```
position: 1 # float position is supported
label: 'Custom folder title'
```

Metadata (front matter)

Markdown documents have metadata at the top called front matter. At the very top of each wiki page, include the following:

Parameter/Type	Description
`title` (string)	Required. The `title` is automatically rendered using the H1 style at the top of the page and is used in navigation if a `sidebar_label` is not included. Keep it short (1-3 words).
`sidebar_label` (string)	Optional. Use a different title for the left sidebar navigation.
`sidebar_position` (number)	Optional. Overrides default position of a doc inside the sidebar directory.
`description` (string)	Optional. This is what appears when the page is referenced in a Google search result.
`keywords` (string[ ])	Optional. A list of meta tags for the document page and search engines.

To see the full list of available options, visit the Docusaurus website.

Introduction

In the first paragraph of the document, provide an overview of the topic and/or set the user's expectation for what they will find on this page.

Table of contents. Headers

For titles and headers, use Sentence case like this. This means only capitalizing the first word and any proper nouns.
Don't end headers with a period.
Don't include your own table of contents (TOC). Both GitHub and Docusaurus automatically generate TOC based on the document's headers.
H1 headers: Never use in a document. The title front matter is automatically generated as an H1.
H2 headers: These headers are shown in the page's TOC. Ensure they concisely reflect the content of each section. Keep it short (1-3 words).
H3 headers: These headers are also shown in the TOC. Ensure the headers represent the content that users may want to access directly. Keep it short (1-3 words).
H4 headers: These headers emphasize things within a subsection of the page. They can be longer than the other headers because they aren't shown in the TOC.

Content

Use only standard Markdown syntax and a limited set of the extended MDX features listed below for document text. Avoid complex formatting, additional MDX capabilities, or HTML tags, as these are not supported by Datagrok widgets.

Tabs are a great option for providing context-driven information. For example, you can use tabs to show code examples in different languages or instructions for different operating systems.

To use tabs, add these lines right below the front matter:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

For each set of tabs, use this code:

 <Tabs groupID="my-group"
    defaultValue="alpha"
    values={[
      {label: 'Alpha', value: 'alpha'},
      {label: 'Beta', value: 'beta'},
    ]}>
  <TabItem value="alpha">Text for alpha.</TabItem>
 <TabItem value="beta">Text for beta.</TabItem>
 </Tabs>
 

To synchronize tabs of the same kind, assign a groupId parameter to all related tabs. This ensures that the chosen selection persists across all instances of tabs with the same groupId.

Example

 <Tabs groupId="operating-systems">
 <TabItem value="windows" label="Windows">Windows instructions.</TabItem>
 <TabItem value="linux" label="Linux">Linux instructions.</TabItem>
 </Tabs>

 <Tabs groupId="operating-systems">
 <TabItem value="windows" label="Windows">More Windows instructions.</TabItem>
 <TabItem value="linux" label="Linux">More Linux instructions.</TabItem>
 </Tabs>

Windows instructions. Linux instructions. More Windows instructions. More Linux instructions.

To display lines of code, use code blocks. Specify which language you are using as Markdown highlights each language differently. You can also include a title with the code block as well.

 ```java title="Custom Title"
 RemoteWebDriver driver = new RemoteWebDriver(url, capabilities);
 ```

Custom Title
RemoteWebDriver driver = new RemoteWebDriver(url, capabilities);

To hide content by default, wrap the content in a details block. Make the summary brief and informative so users know what to expect:

<details>
<summary>How to add a license path</summary>

Your instructions.
   
</details>

How to add a license path

Your instructions.

This is useful for content such as:

An especially large code block.
Information that users may need only occasionally.

You can use different admonitions. Use them sparingly to avoid visual overload:

:::note

This is a note

:::

note

This is a note

:::tip

This is a tip

:::

tip

This is a tip

:::important

This is a note

:::

important

This is a important

:::caution

This is a caution

:::

caution

This is a caution

:::warning

This is a warning

:::

warning

This is a warning

:::note[developers]

This is a note with a custom title

:::

developers

This is a note with a custom title

Use:

Double asterisks (*) for bold text.
Single underscores (_) for italics.

To draw attention to a specific word or phrase.
Explanatory or introductory text at the start of a list item (see the Lists tab for more details).
Mathematical variables and version variables. For example: x + y = 3, version 1.4.x.
The word "optional" for bulleted items in procedures
- Do X.
- Optional. To do Y, open Z.

UI elements, names of tools, apps, packages, etc.
Explanatory or introductory text at the start of a list item (see the Lists tab for more details).

To linked terms
- The Query Editor lets you edit queries. To learn more, see Query Editor.
- A query is a function. Like other functions in Datagrok,...

Capitalize the names and emphasize all user interface elements in bold text. When referring to specific UI text (such as a menu item), use the same capitalization that's displayed in the user interface.

UI naming conventions

Context Panel
Info Pane
Sidebar
Top Menu
Table View
Workspace
Toolbox
Status Ribbon

See the word list to write consistently about dialogs, dropdowns, clearing checkboxes, and more.

When documenting how to navigate through the Datagrok UI:

Start with purpose, then location, then action. This helps users scan the information quickly. Use the arrow key (>) to break a series of cascading UI elements.
- To open the File Manager, on the Sidebar, select Data > Files.
When the UI text sufficiently explains the fields in a section, don't include a task step for every field. Instead, summarize multiple fields in a single task step. Use the phrase 'complete the fields' or an equivalent.
- Right-click the query and select Edit... A dialog opens. In the dialog, set the parameters.
If you are documenting multiple fields and only one field needs explanation, do it in the same step.
- In the dialog, set the connection parameters. When connecting to public buckets in AWS S3, select the Anonymous checkbox.
To describe multiple fields, use unordered list items.
- Set the parameters.
  - When connecting to public buckets in AWS S3, select the Anonymous checkbox.
  - To change the connection credentials, click the Gear icon.

If you use icon images in addition to the text description, do it as follows:

Click the Add new connection (+) icon...

For unordered lists, use asterisks (*) or dashes (-). For numbered lists, use 1. for all items. Markdown automatically numbers the items sequentially when building the site.

If a list starts with an introductory word or phrase, do the following:

Always capitalize the first word in a list.

This is an introductory phrase:
- Completed by this capitalized sentence.
- Also completed by this capitalized sentence.
Don't add commas (,) or semicolons (;) to the ends of list items. If a list item is a complete sentence (with a subject and a verb), add a period at the end. For individual items, add a period only an the end of your list.
Be consistent. Don't mix complete sentences and individual items in a list. Each bulleted item should form a grammatically correct sentence with an introductory word or phrase.
Separate list items from explanatory text with a colon (:). Also, emphasize the list items to make them visually stand out.

This is a procedure:
- First item: this explains the first item.
- Second item: this explains the second item.

Use inline links within your document. Avoid titling links as "here" or "this page". Instead, write the sentence naturally, then wrap the most appropriate phrase with the link:

For more information, see Data Access.
Visualize molecules using chemically-aware viewers.

For documents within the Datagrok help repository, all links should be relative to your Markdown file:

[section in my document](#section-header)
[document in the same folder](other-doc.md)
[document in a subfolder](subfolder/other-doc.md)
[document in a parent folder](../parentFolder/other-doc.md)

Capture screenshots or screen recording using ScreenToGif or a similar tool. Place the images or recordings to a separate directory named img in the same location as your Markdown file. Make sure that the path to the images or recordings is relative to your Markdown file:

![alt text](img/mypng.png)

When you take screenshots/screen recordings:

Capture only the relevant UI. Reduce the size of your browser window as much as possible to keep elements close together and reduce empty space. Exclude any areas of UI that don't illustrate the point.
Capture screenshots and screen recordings at a browser viewport width of 800px and height of 500 pixels. This helps keep scaling consistent. You can use this Chrome extension to quickly set your browser viewport to 800px by 500px.
Don't zoom in or out.
When displayed in the documentation, the text in the image of a screenshot should closely match the text size of the page itself.
PNG and GIF are preferred file formats.

Any videos must be from the Datagrok's YouTube account. To embed a YouTube video on a wiki page:

Copy and paste this code to your page.

<Iframe url="https://www.youtube.com/embed/<your_video_ID>?rel=0"
  width="800px"
  height="500px"
  className="video-container"
  display="initial"
  position="relative"
  allow="accelerometer; autoplay=1; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen
  />

import Iframe from 'react-iframe';

Replace <your_video_ID> with the specific video ID obtained from the YouTube link URL. Make sure to keep ?rel=0 at the end. This ensures that after viewers finish watching the embedded video, they will only be suggested videos from the Datagrok YouTube channel.

Use Markdown rather than HTML as much as possible as MDX may not recognize it. For example, when constructing complex tables, do not use <table>.
Use tags <li><li/> and <br/> when constructing complex tables, for example, creating a list or adding a blank line.

| Column 1    | Column 2                            |
|:------------|:------------------------------------|
| Category    | <li>a</li><li>b</li><br/><li>c</li> |

Column 1	Column 2
Category	a b c

Troubleshooting

A common issue with Docusaurus is the sensitivity of MDX to the placement of code blocks and other text. If you've included a code block or text using common markdown syntax, and things aren't rendering as expected, try the following:

Add an empty line after above and below each code block or text.

When dealing with tabs, either indent the code by five spaces or wrap the MDX tags in an mdx-code-block:

     <Tabs>
     <TabItem value="tab" label="Tab">
  
     Tab contents.

     </TabItem>
     </Tabs>

File format and naming convention​

Sidebar position and label​

Metadata (front matter)​

Introduction​

Table of contents. Headers​

Content​

Troubleshooting​