Page Structure & Markdown Formatting Guide

Creating and Editing Pages in GitBook

How to Edit an Existing Page

1. Locate the page in the folder hierarchy.

   • Each page in GitBook maps directly to a file in the GitHub repository.

   
2. Make required changes (content, formatting, links, images, etc.).

3. Commit the changes.

When You Add a New Page

1

Use the correct file name

• Use lowercase letters.

• Do not use spaces.

• Use dashes (-) between words.

  Example: database-configuration.md

2

Add the page to SUMMARY.md

• GitBook only shows pages listed in SUMMARY.md. Example:

     - [Database Configuration](docs/integrate/database-configuration.md)

3

Commit both files together

• Make sure that:

  • Your new .md file and the update summary.md file are committed in the same commit.

    

How to Add a New Connector Entry

To list a new connector in the documentation, follow the steps below. These steps ensure the connector appears correctly in the Connectors list, Supported Connectors table, and the GitBook sidebar.

1

Add Connector Documentation Page

• Create a new markdown file inside the connectors folder.

  Example: connectors/snow-quick-connect.md

2

Add Logo in Assets Folder

• Place the connector logo in: assets/connector/ directory.

• Logo requirements

  • Background color: #EDF4FD

  • Background box: 536px × 161px

  • Logo size: 72px × 72px

  Example file: assets/connector/servicenow.png

3

Add Entry in connectors.md

• Use the table/card layout format.

  Example:

  <tr>
  <td align="center"><mark style="color:#555555"><strong>ServiceNow Quick Connect</strong></mark></td>
  <td><a href="../assets/connector/70_servicenow.png">ServiceNow Quick Connect</a></td>
  <td><a href="servicenow-quick-connect.md">servicenow-quick-connect.md</a></td>
  </tr>

4

Add Entry in supported-connectors.md

• Include supported versions and entities in the table format.

5

Add Entry in SUMMARY.md

• Include the connector under the Connectors section for sidebar navigation.

  Example:

  * [Connectors](connectors/connectors.md)
    * [ServiceNow Quick Connect](docs/connectors/servicenow-quick-connect.md)

Markdown Basics

• This section provides the essential formatting rules for writing clean, consistent, and well-structured documentation using Markdown. Each topic includes examples, best practices, and recommended usage guidelines to ensure clarity and readability across all content.

• For additional reference, you may also review the official formatting guide: GitBook Formatting Guide

Headings (Titles and Sections)

• Use the # symbol to create headings.

• Each additional # level represents a sub-heading.

• Example

  # H1 – Main Page Heading
  ## H2 – Section Heading
  ### H3 – Subsection Heading

• Guidelines

  • Only H1 and H2 appear in most Table of Contents panels.

  • Do not skip heading levels (use H1 → H2 → H3 in proper order).

  • Keep headings clear and concise.

Text Styling

Formatting Type	How to Write It	Example Output
Bold	**Bold text**	Bold text
Italic	*Italic text*	Italic text
Inline Code	`OIM_HOME/bin`	OIM_HOME/bin
Strikethrough	~~Incorrect text~~	Incorrect text

Lists

Bullet List

• You can create bullet lists using either * or -.

• Example (Using *)

  * First point
  * Second point

  • Rendered Output:

    • First point

    • Second point

• Example (Using -)

  - First point
  - Second point

  • Rendered Output:

    • First point

    • Second point

Numbered List

• Numbered lists use numbers followed by a period:

• Example

  1. Step one
  2. Step two
  3. Step three

• Rendered Output:

1. Step one

2. Step two

3. Step three

Notes and Warnings

• You can create callout-style messages using blockquotes.

  • Note Example:

    > **Note:** Restart service after configuration. 

    • Rendered Output

      Note: Restart service after configuration.

  • Warning Example:

    > **Warning:** Do not delete this folder. 

    • Rendered Output

      Warning: Do not delete this folder.

Angle Brackets < and >

Purpose	How to Write It	Correct Output
Escape < and >	&lt;tag&gt; instead of <tag>	<tag>

Code Blocks (Multiple Lines)

• Use triple backticks to create multi-line code blocks.

• You can also specify the language to enable syntax highlighting.

• JSON Example (How to Write It)

      ```json
      {
        "name": "OpsHub",
        "version": "1.0"
      }
      ```

  • Rendered Output

    {
      "name": "OpsHub",
      "version": "1.0"
    }

• XML Example (How to Write It)

      ```xml
      <configuration>
        <setting key="timeout">30</setting>
      </configuration>
      ```

  • Rendered Output

    <configuration>
    <setting key="timeout">30</setting>
    </configuration>

• Bash Example (How to write It)

      ```bash
      echo "Hello, OpsHub"
      ``` 

  • Rendered Output

    echo "Hello, OpsHub"

Images

• Store all images inside the docs/assets directory.

• Any project should reference images from this central folder.

Image Reference Syntax

Basic Image

• Syntax:

  ![](../assets/image-name.png)

• Rendered Output

  

Centered Image

• Syntax:

  <p align="center">
  <img src="../assets/image-name.png" width="500">
  </p>

• Rendered Output

  

Image Naming Rules

• Avoid spaces in file names.

• Use lowercase for consistency.

• Use dashes (-) or underscores (_).

Image Path Guidelines

Page Location	Correct File Path	Markdown Example
integrate/advanced-scenario/source-delete-sync.md	../../assets/x.png	
help-center/error.md	../assets/x.png	

Embedding Videos

• You can embed videos directly into documentation pages using the {% embed %} tag.

• YouTube Embed Example

  {% embed url="https://youtu.be/Po6K9_UXrfM" %}

• Video Storage Rules

  • Video files cannot be uploaded directly into the repository.

  • To include video content, follow these guidelines:

    • Upload all videos to YouTube.

    • Ensure the video is publicly visible.

    • Use the embed tag to insert the video link into your documentation pages.

Reusable Content

• Reusable content allows you to maintain common text (such as repeated instructions or configuration notes) in a single location and include it across multiple pages.

• This helps ensure consistency, easy maintenance, and automatic updates whenever the shared content changes.

• All reusable Markdown files should be stored inside: .gitbook/includes.

• How to Include a Reusable File:

  • Use the {% include %} tag to pull shared content into any page. Example:

  {% include "../.gitbook/includes/windows-specific-configuration.md" %}

• Notes:

  • Any change in the included file updates all pages automatically.

  • GitBook does not create a TOC (index) for included files.

  • If indexing is required, split content into smaller include files.

Links

Type	Example
Internal	[Integration Setup](../integrate/setup.md)
External	[OpsHub Website](https://www.opshub.com)
Anchor	[Go to Configuration](#configuration)

Tables

Markdown Table

• Markdown supports simple, clean tables for organizing structured information.

• Basic Syntax

  • Use | (pipe characters) to define columns and - (dashes) to separate the header row:

  | Column 1 | Column 2   | Column 3 |
  |----------|:----------:|---------:|
  | Value 1  | Value 2    | Value 3  |

  • Rendered Output

    Column 1	Column 2	Column 3
    Value 1	Value 2	Value 3

• Notes:

  • All rows must have the same number of columns.

  • Alignment is optional and can be added using colons (:).

Card View HTML Table

• You can use cards to create a visually engaging page layout, combining text, links, and optional images in a clean, grid-based structure.

• Example:

  <table data-view="cards" data-full-width="false">
    <thead>
      <tr>
        <th align="center" data-card-cover></th>
        <th data-hidden data-card-target data-type="content-ref"></th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td align="center"><strong>Welcome to OpsHub Guide</strong></td>
        <td><a href="../../README.md">Welcome</a></td>
      </tr>
    </tbody>
  </table>

• Rendered Output:

  Welcome to OpsHub Guide

Conditional Blocks

• Conditional blocks allow you to show or hide content depending on selected product variables (e.g., OIM vs OM4ADO).

  Example: Show content only when SITENAME = "OpsHub Integration Manager":

  {% if "OpsHub Integration Manager" === space.vars.SITENAME %}
  ... content
  {% endif %}

Variable File (vars.yaml)

• Variables are defined inside: .gitbook/vars.yaml

• These variables allow GitBook to automatically render variable's value across all documentation.

  Example (vars.yaml):

  SITENAME: "OpsHub Integration Manager"

Usage

• To insert the value of a variable inside your documentation:

  <code class="expression">space.vars.SITENAME</code>

• Rendered Output:

  This site describes <code class="expression">space.vars.SITENAME</code> features.

  (This replaces the variable with its actual value.)