# 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.
```
* **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:
```markdown
| 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:**
```html
```
* **Rendered Output:**
## 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):
>
> ```yaml
> SITENAME: "OpsHub Integration Manager"
> ```
### Usage
* To insert the value of a variable inside your documentation:
> ```html
> space.vars.SITENAME
> ```
* **Rendered Output:**
> ```
> This site describes space.vars.SITENAME features.
> ```
(This replaces the variable with its actual value.)
