# Markdown

Use the Markdown functions to create formatted text content in your forms. These functions help you create common elements like paragraphs, headings, lists, and more.

{% hint style="info" %}
`<div>` elements are also supported. [See block-level data binding](/content/data-binding.md#block-level-data-binding).
{% endhint %}

## Basic usage

```javascript
import { Composer } from "formsmd";

const composer = new Composer({
  id: "my-form"
});

composer.h1("Heading");
composer.p("This is a **paragraph**.");
composer.hr();
composer.ul([
  "Item 1",
  "Item 2",
  "Item 3"
]);
composer.blockquote("Quote");
composer.code("var a = 5;", {
  language: "javascript"
});
```

Generates the following Markdown:

````
#! id = my-form

# Heading

This is a **paragraph**.

***

- Item 1
- Item 2
- Item 3

> Quote

```javascript
var a = 5;
```
````

***

## Parameters

These parameters are common to all Markdown functions (except for the horizontal rule):

| Name         | Type                                     | Description                                                                                                   |
| ------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `id`         | `string`                                 | The `id` attribute of the element.                                                                            |
| `classNames` | `string[]`                               | The CSS class names of the element. [See the available CSS utility classes](/content/css-utility-classes.md). |
| `attrs`      | `Array<{ name: string, value: string }>` | Other HTML attributes of the element. Each attribute has a `name` and `value` property.                       |

### Code parameter

Additional parameter for the code element:

| Name       | Type     | Description               |
| ---------- | -------- | ------------------------- |
| `language` | `string` | The language of the code. |

***

## Headings

Create heading elements from level 1 (largest) to level 6 (smallest).

### Function overview

```typescript
h1(content: string, params?: object)
h2(content: string, params?: object)
h3(content: string, params?: object)
h4(content: string, params?: object)
h5(content: string, params?: object)
h6(content: string, params?: object)
```

### Example

```javascript
composer.h1("Main title", {
  classNames: ["text-center", "anchored"]
});

composer.h2("Section overview", {
  classNames: ["fw-bold"]
});

composer.h3("Subsection", {
  id: "sub-1"
});
```

Generates the following Markdown:

```
# [.text-center .anchored] Main title

## [.fw-bold] Section overview

### [#sub-1] Subsection
```

***

## Paragraph

Create paragraph elements for body text.

### Function overview

```typescript
p(content: string, params?: object)
```

### Example

```javascript
composer.p("This is a paragraph with custom styling.", {
  classNames: ["fs-lead", "text-accent", "col-6"],
  attrs: [{ name: "data-test", value: "intro-text" }]
});
```

Generates the following Markdown:

```
[.fs-lead .text-accent .col-6 data-test="intro-text"]
This is a paragraph with custom styling.
```

***

## Lists (unordered, ordered, task)

Create unordered (bulleted) and ordered (numbered) lists.

### Function overview

```typescript
ul(items: string[], params?: object)
ol(items: string[], params?: object)
```

### **Unordered list example**

```javascript
composer.ul([
  "First unordered item",
  "Second unordered item",
  "Third unordered item"
], {
  classNames: ["col-6"]
});
```

Generates the following Markdown:

```
- [.col-6]
- First unordered item
- Second unordered item
- Third unordered item
```

### **Ordered list example**

```javascript
composer.ol([
  "First ordered item",
  "Second ordered item",
  "Third ordered item"
], {
  classNames: ["col-4", "xs:col-8"]
});
```

Generates the following Markdown:

```
0. [.col-4 .xs:col-8]
1. First ordered item
2. Second ordered item
3. Third ordered item
```

### **Task list example**

Add the `.list-unstyled` class and use `[ ]` or `[x]` in the `items` to create task lists:

```
composer.ul([
  "[x] Python",
  "[x] JavaScript/TypeScript",
  "[ ] Go"
], {
  classNames: ["list-unstyled"]
});
```

Generates the following Markdown:

```
- [.list-unstyled]
- [x] Python
- [x] JavaScript/TypeScript
- [ ] Go
```

***

## Blockquote

Create blockquote elements for quoted or highlighted content.

### Function overview

```typescript
blockquote(content: string, params?: object)
```

### Example

```javascript
composer.blockquote("Important notice about the survey.", {
  classNames: ["col-4", "xs:col-6"],
  attrs: [{ name: "role", value: "alert" }]
});
```

Generates the following Markdown:

```
> [.col-4 .xs:col-6 role="alert"]
> Important notice about the survey.
```

***

## Code

Create code blocks with optional language specification.

### Function overview

```typescript
code(content: string, params?: object)
```

### Example

```javascript
composer.code(`function greeting() {
  console.log("Hello!");
}`, {
  language: "javascript",
  classNames: ["col-6"]
});
```

Generates the following Markdown:

````
```javascript [.col-6]
function greeting() {
  console.log("Hello!");
}
```
````

***

## Horizontal rule

Create horizontal line dividers.

### Function overview

```typescript
hr()
```

### Example

```javascript
composer.h2("Section 1");
composer.p("First section content");
composer.hr();
composer.h2("Section 2");
```

Generates the following Markdown:

```
## Section 1

First section content

***

## Section 2
```

{% hint style="info" %}
If the slide delimiter is set to `"***"`, horizontal rules will automatically use `"---"` instead to avoid confusion with slide breaks.
{% endhint %}

***

## Free-form content

Add arbitrary content that will be included exactly as written.

### Function overview

```typescript
free(content: string)
```

### Example

```javascript
composer.free(`# Hello world

This is some free-form content that will be included exactly as written, *including* 
any Markdown formatting.`);
```

Generates the following Markdown:

```
# Hello world

This is some free-form content that will be included exactly as written, *including* 
any Markdown formatting.
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.forms.md/content/markdown.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.