modxorg · Mark-H · Jul 31, 2026 · Jul 31, 2026
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -15,5 +15,6 @@
   "no-trailing-punctuation": {
     "punctuation": ".,;:"
   },
-  "no-duplicate-header": false
+  "no-duplicate-header": false,
+  "no-bare-urls": false
 }
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -57,4 +57,4 @@ The name of your file (and thus, the documentation URL) does **not** have to mat
 
 If you're new to git or GitHub, or more of a visual learner, the following screencast will show you how you can edit the documentation with just the browser.
 
-<iframe sandbox="allow-same-origin allow-forms allow-popups allow-scripts" src="https://player.vimeo.com/video/330122657?byline=0" width="640" height="360" frameborder="0" allow="autoplay; fullscreen" allowfullscreen></iframe>
+https://vimeo.com/330122657
diff --git a/en/building-sites/integrating-templates/video-quick-start.md b/en/building-sites/integrating-templates/video-quick-start.md
@@ -10,13 +10,13 @@ _old_uri: "2.x/getting-started/video-quick-start-series/"
 
 MODX Cloud is a rapid development platform built to make tasks like installation, upgrading, and migrating MODX sites a one-button affair. This video shows you how to sign up for an account and get started with MODX in minutes.
 
-<iframe sandbox="allow-same-origin allow-forms allow-popups allow-scripts" src="https://player.vimeo.com/video/60298110" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
+https://vimeo.com/60298110
 
 ### Using cPanel
 
 MODX's default installation software makes it easy to deploy on almost any server environment that meets the minimum requirements. This video shows you how to install MODX on a common cPanel-enabled hosting account in just a few minutes.
 
-<iframe sandbox="allow-same-origin allow-forms allow-popups allow-scripts" src="https://player.vimeo.com/video/68094979" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
+https://vimeo.com/68094979
 
 ## Importing Your HTML Into MODX
 
@@ -26,28 +26,28 @@ This video series walks you step-by-step through the process of integrating cust
 
 Watch this tutorial to learn how to integrate your own HTML/CSS/Javascript into a MODX Template, with simple-to-use placeholders for dynamic content.
 
-<iframe sandbox="allow-same-origin allow-forms allow-popups allow-scripts" src="https://player.vimeo.com/video/60884063" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
+https://vimeo.com/60884063
 
 ### Using Chunks
 
 This tutorial shows you how to manipulate your own front-end code using Chunks.
 
-<iframe sandbox="allow-same-origin allow-forms allow-popups allow-scripts" src="https://player.vimeo.com/video/62971149" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
+https://vimeo.com/62971149
 
 ### PHP Snippets
 
 Integrate your own PHP Snippets, or leverage a powerful library of pre-packaged Snippets that extend MODX's core functionality on an ad-hoc basis. Use only what you need for your site. Learn the basics in this tutorial.
 
-<iframe sandbox="allow-same-origin allow-forms allow-popups allow-scripts" src="https://player.vimeo.com/video/68277695" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
+https://vimeo.com/68277695
 
 ### Template Variables
 
 Template Variables ("TVs") are simply custom fields: easy-to-use input fields for site admins and content editors, yet full control for designers and developers. Learn all about them in this tutorial.
 
-<iframe sandbox="allow-same-origin allow-forms allow-popups allow-scripts" src="https://player.vimeo.com/video/72873121" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
+https://vimeo.com/72873121
 
 ### MODX Elements Combined
 
 This tutorial shows you how to combine the various Elements discussed in previous videos to fully leverage the power and flexibility of MODX. By the end of this video, you should have a basic understanding of how to use Snippets, TVs, Chunks and Templates to build a simple yet dynamic custom website in MODX.
 
-<iframe sandbox="allow-same-origin allow-forms allow-popups allow-scripts" src="https://player.vimeo.com/video/74035603" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
+https://vimeo.com/74035603
diff --git a/en/contribute/documentation/index.md b/en/contribute/documentation/index.md
@@ -76,12 +76,61 @@ The name of your file (and thus, the documentation URL) does **not** have to mat
 
 To test if a translation is properly connected, you'll need to run the application on a local environment and execute `php docs.php index:translations`. See the DocsApp repository for more.
 
+## Markdown, HTML, and media
+
+Write pages in [CommonMark](https://commonmark.org/) Markdown (with tables, footnotes, strikethrough, and similar extras). Prefer Markdown for structure and formatting.
+
+### Raw HTML is not rendered
+
+Raw HTML in documentation sources is **stripped** and will not appear on the site. Do not use tags such as `` `<div>` ``, `` `<span>` ``, `` `<br>` ``, `` `<iframe>` ``, `` `<script>` ``, or `` `<video>` `` in page content. Put example HTML inside fenced code blocks so it shows as code instead of being removed:
+
+```` plain
+```html
+<div class="example">Sample markup</div>
+```
+````
+
+Front matter values (for example `title` and `description`) should be plain text, not HTML.
+
+### Embedded videos (YouTube, Vimeo, GitHub)
+
+To embed a video or other supported rich content, put the **https URL alone on its own line**. Do not wrap it in an iframe or other HTML. Angle brackets (`<https://...>`) and Markdown link syntax are not treated as embeds.
+
+Supported hosts today: **YouTube**, **Vimeo**, and **GitHub**.
+
+``` plain
+Watch this overview:
+
+https://vimeo.com/330122657
+```
+
+If the URL cannot be embedded, it falls back to a normal link. 
+
+### Images
+
+Use standard Markdown image syntax. Relative paths resolve from the current file's directory:
+
+``` plain
+![Setup options](setup-opt1.png)
+```
+
+### Local videos
+
+For short demos stored next to the page (`.mp4`, `.webm`, or `.ogg`), use the **same image syntax**. DocsApp turns those into an in-page video player and serves the file from the docs tree:
+
+``` plain
+![Basic use demo](basic-use.mp4)
+```
+
+Prefer hosting longer videos on Vimeo or YouTube and embedding them with a bare URL as above.
+
 ## Screencast
 
 If you're new to git or GitHub, or more of a visual learner, the following screencast (from 2019) will show you how you can edit the documentation with just the browser.
 
-<iframe sandbox="allow-same-origin allow-forms allow-popups allow-scripts" src="https://player.vimeo.com/video/330122657?byline=0" width="640" height="360" frameborder="0" allow="autoplay; fullscreen" allowfullscreen></iframe>
+https://vimeo.com/330122657
 
 ## See also
 
-1. [Markdown rules document](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md)
+1. [Content Style Guide](style-guide)
+2. [Markdown rules document](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md)
diff --git a/en/contribute/documentation/style-guide.md b/en/contribute/documentation/style-guide.md
@@ -282,35 +282,50 @@ Some important recommendations:
 
 ## Page Formatting and Markup
 
-There is a limited set of formatting elements in order to make it easy for editors and provide consistent formatting for readers. The following shows what formats are available for HTML and special formats for the MODX Documentation
-
-### Permitted HTML Markup
-
-| Format Type    | Usage                                                                                                                                        | Example |
-| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| Normal Text    | This is the text format used for all paragraph text and inside tables.                                                                       |         |
-| Bold           | (TBD)                                                                                                                                        |         |
-| Italics        | (TBD)                                                                                                                                        |         |
-| Bulleted Lists | (TBD)                                                                                                                                        |         |
-| Numbered Lists | (TBD)                                                                                                                                        |         |
-| Indents        | Reserve indentation for use in creating nested or child lists. Paragraphs should not be                                                      |         |
-| Images         | (TBD)                                                                                                                                        |         |
-| Media          | (TBD)                                                                                                                                        |         |
-| Table          | (TBD)                                                                                                                                        |         |
-| Links          | (TBD)                                                                                                                                        |         |
-| Text-Alignment | Reserve text-alignment for table cells. It should not be used to center, right or jusitfy text. Paragraph and headings must be left-aligned. |         |
-
-### Special Formats
-
-| Format Type | Usage                                                                                                                                                                            | Example |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| PHP Code    | This is a special macro-format for wrapping code examples including PHP, HTML, CSS and Javascript. This will enable syntax highlighting and enhance the readibility of the page. |         |
-| Note        | (TBD)                                                                                                                                                                            |         |
-| Warning     | (TBD)                                                                                                                                                                            |         |
-| Danger      | (TBD)                                                                                                                                                                            |         |
-| Info        | (TBD)                                                                                                                                                                            |         |
-
-Other HTML elements such as divs, spans, blockquotes, address and etc. should not be used. This makes maintaining the documentations more difficult and can potentially create issues with layouts. Classes and IDs should not be used in markup. Special classes used when formatting in HTML are created by the Special Format macros listed above.
+Documentation pages are Markdown, not free-form HTML. Use Markdown for headings, lists, links, tables, emphasis, and fenced code blocks. [DocsApp](https://github.com/modxorg/DocsApp) **strips raw HTML** from page bodies, so tags written outside code fences do not appear on the site.
+
+### Markdown formatting
+
+| Format | Markdown | Notes |
+| ------ | -------- | ----- |
+| Headings | `#` … `######` | One `#` heading per page title is usually enough; start section headings at `##`. |
+| Bold / italic | `**bold**`, `_italic_` | Use sparingly for UI labels and emphasis. |
+| Lists | `-` or `1.` | Nest lists with indentation when needed. |
+| Links | `[label](https://example.com)` or `[label](../other-page)` | Prefer relative links for other docs pages. |
+| Images | `![alt text](image.png)` | Keep image files next to the page when practical. |
+| Tables | GitHub-flavored pipe tables | Good for option lists and comparisons. |
+| Code | Fenced blocks with a language tag (for example `php`, `html`, `bash`) | Use for PHP, HTML, CSS, JS, and shell examples. |
+
+Do **not** use layout HTML (`` `<div>` ``, `` `<span>` ``, inline styles, alignment attributes, custom classes or IDs). Those are stripped and make maintenance harder.
+
+### Media embeds
+
+| Media | How to include it |
+| ----- | ----------------- |
+| YouTube / Vimeo / GitHub | Put the bare `https://` URL alone on its own line (not `<…>` or `[text](url)`). DocsApp embeds it when the host is allowed. |
+| Local video (`.mp4`, `.webm`, `.ogg`) | Use image syntax: `![Demo](demo.mp4)`. DocsApp renders a video player. |
+| Screenshots / diagrams | Use `![description](file.png)` (or `.jpg` / `.gif` / `.webp`). |
+
+Wrong (stripped, no embed):
+
+``` plain
+<iframe src="https://player.vimeo.com/video/123"></iframe>
+<video src="demo.mp4" controls></video>
+```
+
+Correct:
+
+``` plain
+https://vimeo.com/123
+
+![Demo](demo.mp4)
+```
+
+Front matter fields such as `title` and `description` must be plain text, not HTML.
+
+### Callouts and notes
+
+Callout-style boxes (note, warning, and similar) are controlled by front matter on the page (for example `note:`) or by normal Markdown emphasis, not by custom HTML macros.
 
 ## Final checklist
 
@@ -320,3 +335,4 @@ Before considering a document or change complete, it is a good idea to perform t
 - It is concise? Does it have a clear communication style?
 - It is coherent? Does the text jumps from topic to topic?
 - It is grammatically correct? Have you spell checked the text? Have you asked a native speaker to proof-read your text
+- Does it avoid raw HTML outside code fences? Are embeds bare URLs or Markdown images/videos as documented above?
diff --git a/en/extras/fred/themer/themes.md b/en/extras/fred/themer/themes.md
@@ -71,10 +71,7 @@ Save this Element, go back to the front-end of your Resource, and refresh the pa
 
 Click on the orange Elements stacked boxes icon or the MODX icon in the launcher at the bottom left of the page. In the sidebar Elements tab, you should now see the categories you created earlier in step 4. Hover the `Text` category to see your freshly created `H1 Heading` Element and drag it into the empty dropzone.
 
-<video width="640" height="480" controls>
-  <source src="basic-use.mp4" type="video/mp4">
-Your browser does not support the video tag.
-</video>
+![Basic use demo](basic-use.mp4)
 
 Congratulations, you just added your first Element to a page using Fred!
 
@@ -88,10 +85,7 @@ Let’s create another Element for a single paragraph:
 4. Drag this new Element beneath the previously created title, and drop it in place
 5. Change the text and save
 
-<video width="640" height="480" controls>
-  <source src="basic-use-2.mp4" type="video/mp4">
-Your browser does not support the video tag.
-</video>
+![Basic use continued](basic-use-2.mp4)
 
 ## Exporting a Theme
 

diff --git a/en/extras/fx2themebase/fx2.how-to-use-fx2.md b/en/extras/fx2themebase/fx2.how-to-use-fx2.md
@@ -6,7 +6,7 @@ _old_uri: "revo/fx2themebase/fx2.how-to-use-fx2"
 
 ## How to Use FX2 - Overview
 
-<iframe sandbox="allow-same-origin allow-forms allow-popups allow-scripts" src="https://player.vimeo.com/video/76491147" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
+https://vimeo.com/76491147
 
 FX2 was designed for 2 different types of users. MODX developers and theme authors can use it as a "foundation" (see what I did there?) for building MODX site packages that end users can customize easily. End users _could_ use FX2 to power their site, as a "free" theme, but very little attention has been paid to the design and styling. The FX2 templates use Zurb's sample HTML templates, largely unmodified, except for the dynamic MODX magical bits.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -57,4 +57,4 @@ The name of your file (and thus, the documentation URL) does not have to mat

		If you're new to git or GitHub, or more of a visual learner, the following screencast will show you how you can edit the documentation with just the browser.

		<iframe sandbox="allow-same-origin allow-forms allow-popups allow-scripts" src="https://player.vimeo.com/video/330122657?byline=0" width="640" height="360" frameborder="0" allow="autoplay; fullscreen" allowfullscreen></iframe>
		https://vimeo.com/330122657