jandieman/dotjuice-plugin-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs pass: add widget screenshots and expand the user guides

Browse Source 
Add 21 screenshots across the Elementor Tools docs and rework the pages
around them: clearer opening lines, settings tables that state defaults,
and callouts for the parts people trip over. Also refreshes the Pro
getting-started, Custom Product Tabs and Product Filter pages, plus the
matching marketing copy.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Johan
2026-07-31 06:13:57 +00:00
parent 1d9b26b108
commit f4838865c9
43 changed files with 672 additions and 253 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
docs/dotjuice-elementor-tools/widgets/markdown-widget.md
View File

@@ -1,27 +1,80 @@
# 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 you specify directly in the visitor's browser and converts it to HTML on the fly. Because the fetch happens in the browser, the source file needs to allow cross-origin requests — raw file URLs from GitHub (`raw.githubusercontent.com`) work well; a URL that isn't set up to allow this will fail to load, with a note in the browser's developer console.
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 | What it does |
|---|---|
| **Markdown File URL** | The direct URL to the raw Markdown file (not a formatted preview page — for GitHub, use the "Raw" file link, not the normal file view). |
| 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 | What it does |
|---|---|
| **Text Color** | Sets the base text color for the rendered content. |
| 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 additional classes — headings, code blocks, and other elements will take on whatever styling your theme already applies to those standard HTML tags. If you want the rendered Markdown to look a specific way, style it through your theme's typography settings for headings, lists, and `<pre>`/`<code>` blocks, since this widget doesn't apply its own detailed formatting beyond the base text color.
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
- **Use the raw file URL, not a formatted view.** For a GitHub file, click "Raw" on the file page and use that URL — the normal GitHub file-viewer page returns an HTML page, not the Markdown source, and won't render correctly.
- The content loads via 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, check your browser's developer console: the two most common causes are an incorrect URL (view page instead of raw file) or the source not allowing cross-origin requests from your domain.
- **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.