# Markdown Widget

Render a live Markdown file — a README, changelog, or documentation page — directly in your site, always showing the current version.

Found in the Elementor panel under **Dotjuice → Markdown**.

![The Markdown widget controls in the Elementor panel](../assets/img/markdown-widget-controls.png)
*Screenshot: the widget selected in the editor with the **Settings** section open, showing the Markdown Source dropdown and the Markdown File URL field.*

## How it works

The widget fetches the Markdown file **on your server**, embeds the document in the page, and converts it to HTML in the visitor's browser. Fetched files are cached for 15 minutes.

Because the fetch is server-side, the source does **not** need to permit cross-origin requests. Raw URLs from GitHub, Gitea, or a private self-hosted server all work.

## Content settings

| Setting | Default | What it does |
|---|---|---|
| **Markdown Source** | External URL | Choose between fetching a URL or using a file from the Media Library. |
| **Markdown File URL** | — | Direct URL to the raw Markdown file. Supports dynamic content, so the URL can come from a custom field. |
| **Markdown File** | — | Upload a `.md` file or pick one from the Media Library. Shown when Source is set to Uploaded file. |

:::caution Use the raw file URL
For a GitHub file, click **Raw** and use that URL. The normal file-viewer page returns an HTML page rather than Markdown source, and won't render correctly. The same applies to Gitea and most other Git hosts.
:::

## Styling

| Setting | Default | What it does |
|---|---|---|
| **Text Color** | `#000000` | Base text colour for the rendered content. |

The Markdown is converted to plain semantic HTML — headings, paragraphs, lists, code blocks, links — with no extra classes. Those elements inherit whatever styling your theme already applies to standard HTML tags. To control the appearance, style headings, lists and `<pre>`/`<code>` through your theme's typography settings; this widget doesn't impose its own formatting beyond the base text colour.

## Shortcode

Anywhere the widget can't go — a WooCommerce product tab, a text editor, a template — use the shortcode instead:

```
[dj_markdown url="https://example.com/changelog.md"]
```

### Pulling the URL from a custom field

Rather than a fixed URL, point the shortcode at a field name and it reads that field from the post being displayed:

```
[dj_markdown acf_field="changelog_url"]
```

This is the practical way to show a different document per post or product. Add a URL field to your products, place one shortcode in a tab or template, and every product renders its own file.

The field is read from ACF when installed, and falls back to a plain custom field otherwise — so it works either way. ACF **URL**, **Text**, **Link** and **File** field types are all handled.

![A per-product changelog rendered inside a product tab](../assets/img/markdown-widget-product-tab.png)
*Screenshot: a product page with a "Changelog" tab open, showing a rendered Markdown changelog pulled from that product's own field.*

### All attributes

| Attribute | What it does |
|---|---|
| `url` | The Markdown URL to fetch. Takes precedence if both are given. |
| `acf_field` | Name of a field holding the URL. Also accepts `acf-field` or `field`. |
| `post_id` | Read the field from this post instead of the one being displayed. |
| `cache` | Cache lifetime in seconds. Use `cache="0"` to always fetch fresh. |
| `class` | Extra CSS class on the container, for styling. |

`[dj-markdown]` works as an alias if you prefer the hyphen.

:::tip Pairing it with product tabs
The Pro plugin's [Woo Custom Product Tabs](../../dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs.md) runs shortcodes in its custom tab content, which is what makes the per-product changelog pattern above work.
:::

## Good to know

- **Only http:// and https:// URLs are accepted.** Other schemes are rejected, so a Markdown file must be reachable over the web — a local file path won't work.
- **The rendered HTML is produced by JavaScript** after the page loads, so it won't appear in "view source". This is expected and doesn't affect what visitors see.
- **If nothing appears and you're logged in as an editor or administrator**, the widget and shortcode both print the reason directly on the page. Visitors never see those messages — they get an HTML comment instead.
- **Edits to a source file take up to 15 minutes to show** because of the cache. Add `cache="0"` to the shortcode while you're setting things up, then remove it.