# Markdown

Welcome to the BoxLang Markdown module. This provides native support for Markdown in BoxLang based on the popular Flexmark library.

```
# For Operating Systems using our Quick Installer.
install-bx-module bx-markdown

# Using CommandBox to install for web servers.
box install bx-markdown
```

### Built In Functions (BIFs)

The following BIFs are available for use in your BoxLang code:

* `markdown()`
* `HtmlToMarkdown()`

#### `markdown()`

Converts markdown markup to HTML.

```js
markdown( txt )
```

**Arguments:**

* `txt` - The markdown text to convert to HTML

**Returns:**

The HTML equivalent string of the markup.

**Example:**

```js
markdown( "# Hello World" )
```

**Output:**

```html
<h1>Hello World</h1>
```

#### `HtmlToMarkdown()`

Converts HTML markup to markdown.

```js
HtmlToMarkdown( markup )
```

**Arguments:**

* `markup` - The HTML string to convert.

**Returns:**

* The markdown equivalent string of the markup.

**Example:**

```js
HtmlToMarkdown( "<h1>Hello World</h1>" )
```

**Output:**

```markdown
# Hello World
```

### Components

This module also provides a `bx:markdown` component that can be used to convert markdown to HTML in a wrapping approach. You can use it in script or in the templating language. The following attributes are available:

* `variable` - The variable to store the output in. If not set, the output will be written to the response.

Example with variable:

```js
// The content of the component will be parsed and stored in the variable: data.
bx:markdown variable="data"{
	writeOutput( "## Hola" )
}
```

Example with no variable, outputs to the response:

```js
bx:markdown{
	writeOutput( "## Hola" )
}
```

Example in the templating language using a variable:

```html
<bx:markdown variable="html">
	## Hola Mundo

	My beautiful markdown text
</bx:markdown>
<bx:output>#html#</bx:output>
```

Example in the templating language with no variable:

```html
<bx:markdown>
	## Hola mundo

	This is a markdown test
</bx:markdown>
```

### Settings

A subset of the flexmark options are supported. These can be configured in your `boxlang.json` in the `modules` section:

```js
"modules" : {

	"cbmarkdown" : {
		"enabled" : true,
		"settings" : {
			// Looks for www or emails and converts them to links
			"autoLinkUrls"                  : true,
			// Creates anchor links for headings
			"anchorLinks"                   : true,
			// Set the anchor id
			"anchorSetId"                   : true,
			// Set the anchor id but also the name
			"achorSetName"                  : true,
			// Do we create the anchor for the full header or just before it. True is wrap, false is just create anchor tag
			"anchorWrapText"                : false,
			// The class(es) to apply to the anchor
			"anchorClass"                   : "anchor",
			// raw html prefix. Added before heading text, wrapped or unwrapped
			"anchorPrefix"                  : "",
			// raw html suffix. Added before heading text, wrapped or unwrapped
			"anchorSuffix"                  : "",
			// Enable youtube embedded link transformer
			"enableYouTubeTransformer"      : false,
			// default null, custom inline code open HTML
			"codeStyleHTMLOpen"             : "<code>",
			// default null, custom inline code close HTML
			"codeStyleHTMLClose"            : "</code>",
			// default "language-", prefix used for generating the <code> class for a fenced code block, only used if info is not empty and language is not defined in
			"fencedCodeLanguageClassPrefix" : "language-",
			// Table options
			"tableOptions"                  : {
				// Treat consecutive pipes at the end of a column as defining spanning column.
				"columnSpans"                 : true,
				// Whether table body columns should be at least the number or header columns.
				"appendMissingColumns"        : true,
				// Whether to discard body columns that are beyond what is defined in the header
				"discardExtraColumns"         : true,
				// Class name to use on tables
				"className"                   : "table",
				// When true only tables whose header lines contain the same number of columns as the separator line will be recognized
				"headerSeparationColumnMatch" : true
			}
		}
	}
	// end markdown config

};
```

### GitHub Repository and Reporting Issues <a href="#github-repository-and-reporting-issues" id="github-repository-and-reporting-issues"></a>

Visit the [GitHub repository](https://github.com/ortus-boxlang/bx-markdown) for release notes. You can also file a bug report or improvement suggestion via [Jira](https://ortussolutions.atlassian.net/secure/CreateIssueDetails!init.jspa?pid=13359\&components=27183\&issuetype=1).


---

# 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://boxlang.ortusbooks.com/boxlang-framework/modularity/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.