diff --git a/.markdownlint.json b/.markdownlint.json index 7940a8511..89d2ce599 100644 --- 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 index 4d6a33139..72f9b9ce2 100644 --- 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. - +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 index e1786b8de..cb1e9a0e9 100644 --- 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. - +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. - +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. - +https://vimeo.com/60884063 ### Using Chunks This tutorial shows you how to manipulate your own front-end code using Chunks. - +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. - +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. - +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. - +https://vimeo.com/74035603 diff --git a/en/contribute/documentation/index.md b/en/contribute/documentation/index.md index a32e3f97e..7f427b8f9 100644 --- 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 `` `
` ``, `` `` ``, `` `
` ``, `` ` +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 index a2f6dae93..1ab6fa0ba 100644 --- 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 (`` `
` ``, `` `` ``, 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 + + +``` + +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 index b710275fa..a3f26e3f2 100644 --- 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. - +![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 - +![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 index 59b38f3af..aa7b0f216 100644 --- 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 - +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. diff --git a/ru/building-sites/integrating-templates/video-quick-start.md b/ru/building-sites/integrating-templates/video-quick-start.md index 8fd970c11..d333d7cf4 100644 --- a/ru/building-sites/integrating-templates/video-quick-start.md +++ b/ru/building-sites/integrating-templates/video-quick-start.md @@ -9,13 +9,13 @@ translation: "building-sites/integrating-templates/video-quick-start" MODX Cloud - это платформа быстрой разработки, созданная для того, чтобы такие задачи, как установка, обновление и миграция сайтов MODX, выполнялись одним нажатием кнопки. В этом видео показано, как зарегистрировать учетную запись и начать работу с MODX за считанные минуты. - +https://vimeo.com/60298110 ### Использование cPanel Установочное ПО MODX по умолчанию упрощает развертывание практически на любой серверной среде, отвечающей минимальным требованиям. В этом видео показано, как установить MODX на общую учетную запись хостинга с поддержкой cPanel всего за несколько минут. - +https://vimeo.com/68094979 ## Импорт вашего HTML в MODX @@ -25,28 +25,28 @@ MODX Cloud - это платформа быстрой разработки, со Посмотрите это руководство, чтобы узнать, как интегрировать свой собственный HTML/CSS/Javascript в шаблон MODX с простыми в использовании заполнителями для динамического содержимого. - +https://vimeo.com/60884063 ### Использование чанков Из этого туториала вы узнаете, как манипулировать собственным кодом внешнего интерфейса с помощью чанков. - +https://vimeo.com/62971149 ### PHP сниппеты Интегрируйте свои собственные PHP сниппеты или используйте мощную библиотеку предварительно упакованных сниппетов, которые расширяют основные функциональные возможности MODX на специальной основе. Используйте только то, что вам нужно для вашего сайта. Изучите основы этого урока. - +https://vimeo.com/68277695 ### Переменные шаблона Переменные шаблона («TV») - это просто настраиваемые поля: удобные поля ввода для администраторов сайтов и редакторов контента, но полный контроль для дизайнеров и разработчиков. Узнайте все о них в этом уроке. - +https://vimeo.com/72873121 ### MODX комбинированные элементы Из этого туториала Вы узнаете, как объединить различные элементы, рассмотренные в предыдущих видеороликах, чтобы полностью использовать мощь и гибкость MODX. К концу этого видео вы должны иметь общее представление о том, как использовать сниппеты, TVs, блоки и шаблоны для создания простого, но динамичного настраиваемого веб-сайта в MODX. - +https://vimeo.com/74035603 diff --git a/ru/contribute/documentation/index.md b/ru/contribute/documentation/index.md index ce0c6f1be..2cf1b17d7 100644 --- a/ru/contribute/documentation/index.md +++ b/ru/contribute/documentation/index.md @@ -81,7 +81,7 @@ translation: "getting-started/friendly-urls" Если вы новичок в git или GitHub или являетесь более опытным специалистом по визуальному обучению, следующий скринкаст (с 2019 г.) покажет вам, как можно редактировать документацию с помощью только браузера. - +https://vimeo.com/330122657 ## Смотрите также