diff options
| -rw-r--r-- | files/zh-cn/mdn/structures/macros/index.html | 34 | ||||
| -rw-r--r-- | files/zh-cn/mdn/structures/macros/other/index.html | 92 | ||||
| -rw-r--r-- | files/zh-cn/mdn/yari/index.html | 1 | ||||
| -rw-r--r-- | files/zh-tw/mdn/yari/index.html | 24 |
4 files changed, 118 insertions, 33 deletions
diff --git a/files/zh-cn/mdn/structures/macros/index.html b/files/zh-cn/mdn/structures/macros/index.html index b41123ab3f..4227374bac 100644 --- a/files/zh-cn/mdn/structures/macros/index.html +++ b/files/zh-cn/mdn/structures/macros/index.html @@ -1,5 +1,5 @@ --- -title: Macros +title: 使用宏 slug: MDN/Structures/Macros tags: - Guide @@ -11,36 +11,32 @@ translation_of: MDN/Structures/Macros --- <div>{{MDNSidebar}}</div> -<p><a href="/en-US/docs/Project:MDN/Kuma" title="/en-US/docs/Project:MDN/Kuma">Kuma</a> 平台为 MDN 提供了强大的宏系统——<a href="/en-US/docs/Project:MDN/Kuma/KumaScript_guide" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript</a>，使得 MDN 能够自动地去做各种东西。本文提供一些信息以便大家知道如何使用 MDN 上的文章内的宏。</p> +<p><span class="seoSummary">为了自动化执行某些工作，<a href="/zh-CN/docs/MDN/Yari">Yari</a> 平台提供了一个强大的宏系统——<a href="/zh-CN/docs/MDN/Tools/KumaScript">KumaScript</a>。本文提供了一些相关信息，方便你在参与编辑 MDN 时，使用这些宏。</span></p> -<p>鉴于本文只是 KumaScript 的简介，<a href="/zh-CN/docs/Project:MDN/Kuma/KumaScript_guide" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript 指南</a>提供了更深入的内容。</p> +<p>本文只是简要介绍了 KumaScript，<a href="/zh-CN/docs/MDN/Kuma/KumaScript_guide" title="/zh-CN/docs/MDN/Kuma/KumaScript_guide">KumaScript 指南</a>提供了更深入的内容，帮助你使用和掌握它。</p> -<h2 id="宏是如何实现的">宏是如何实现的</h2> +<h2 id="How_macros_are_implemented">宏是如何实现的</h2> -<p>MDN使用的Macros(宏)是基于<a href="http://nodejs.org/" title="http://nodejs.org/">Node.js</a>执行环境，并在服务端执行运行。这里包括了大量的代码库，另外对此还提供了丰富的wiki说明文档内容。如果你希望能学习到更多的内容，可以查看 <a href="/en-US/docs/Project:MDN/Kuma/KumaScript_guide" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript 指南</a>， <a href="/en-US/docs/Project:MDN/Kuma/KumaScript_reference" title="/en-US/docs/Project:MDN/Kuma/KumaScript_reference">KumaScript reference</a> 则提供了更多关于这些代码库和KumaScript的API的实现机理。</p> +<p>MDN 使用宏是基于运行于服务器上的 JavaScript 代码实现的，并由 <a href="http://nodejs.org/">Node.js</a> 解释执行。在此之上，已经实现了一个丰富的工具库，让宏可以与这个平台及其中的内容进行互动。</p> -<h2 id="在文章中使用宏">在文章中使用宏</h2> +<h2 id="Using_a_macro_in_content">在文章中使用宏</h2> -<p>要实际使用宏，只需将对宏的调用括在一对双括号中，其参数（如果有）括在括号中;如下：</p> +<p>要实际使用宏，只需将对宏的调用和可能需要的参数写在一对双括号中，如下：</p> <pre class="notranslate">\{{macroname(parameter-list)}}</pre> <p>关于宏调用的一些注意事项：</p> <ul> - <li>宏名称区分大小写，但有些尝试是为了纠正常见的大写错误;即使宏名称在其中使用大写，您也可以使用全部小写，并且您可以将名称通常以小写字母开头的宏大写。</li> - <li>参数以逗号分隔</li> - <li>如果没有参数，您可以完全省略括号; <code>\{{macroname()}}</code> 和 <code>\{{macroname}}</code> 完全相同。</li> - <li>数字参数可以是引号，也可以不是。这取决于您（但是，如果您的版本号中包含多个小数，则需要在引号中）</li> - <li>如果您遇到错误，请仔细检查您的代码。如果仍然无法弄清楚发生了什么，请参阅<a href="/en-US/docs/MDN/Kuma/Troubleshooting_KumaScript_errors">Troubleshooting KumaScript errors</a>以获取帮助。</li> + <li>宏的名称区分大小写，但一些常见的大小写错误也可以在执行时被纠正。比如将某个名称中含有大写的宏，全部使用小写字母，或者将某些名字以小写开头的宏大写。</li> + <li>参数以逗号分隔。</li> + <li>如果没有参数，括号可以省略：<code>\{{macroname()}}</code> 和 <code>\{{macroname}}</code> 的效果是。</li> + <li>数字参数可以是引号，也可以不是。这取决于您（但是，像版本号这类可能被识别成小数的参数，则包含在引号中）</li> + <li>如果遇到错误，请先仔细检查代码。如果仍然无法弄清楚发生了什么，请参阅<a href="/zh-CN/docs/MDN/Tools/KumaScript/Troubleshooting">排查 KumaScript 中的错误</a>以获取帮助。</li> </ul> -<p>宏被高度缓存;对于任何一组输入值（参数和环境值，例如运行宏的URL），结果都会被存储和重用。这意味着宏仅在输入发生变化时才实际运行。</p> +<p>宏的几乎所有执行结果都会被缓存，以便被重用来加快执行速度。这意味着宏仅在输入发生变化时才实际运行，包括调用时的参数以及环境值（例如这个宏被调用时所在的路径）。</p> -<div class="note"> -<p><strong>注意:</strong> 您可以通过在浏览器中强制刷新页面（即转移重新加载）来强制重新评估页面上的所有宏。</p> -</div> +<p>宏既可以用来做一些简单的工作，比如插入更大的文本块或从MDN的另一部分交换内容一样简单，也可以通过搜索站点的各个部分，设置输出样式和添加链接来构建整个内容索引。</p> -<p>宏可以像插入更大的文本块或从MDN的另一部分交换内容一样简单，也可以通过搜索站点的各个部分，设置输出样式和添加链接来构建整个内容索引。</p> - -<p>您可以在<a href="/en-US/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros" title="/en-US/docs/Project:MDN/Contributing/Custom_macros">Commonly-used macros</a>页面上阅读我们最常用的宏;另外，这里有<a href="https://developer.mozilla.org/en-US/docs/templates" title="https://developer.mozilla.org/en-US/docs/templates">complete list of all macros</a>。大多数宏都有内置的文档，作为顶部的注释。</p> +<p>您可以在<a href="/zh-CN/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros">常用的宏</a>页面看到一些我们最常用到的宏，还可以在我们 Github 的仓库中，浏览<a href="https://github.com/mdn/yari/tree/master/kumascript/macros">所有可用的宏</a>。大多数宏顶部的注释中，都有内置的文档帮助你了解它的作用。</p> diff --git a/files/zh-cn/mdn/structures/macros/other/index.html b/files/zh-cn/mdn/structures/macros/other/index.html new file mode 100644 index 0000000000..d9dd6f2ea3 --- /dev/null +++ b/files/zh-cn/mdn/structures/macros/other/index.html @@ -0,0 +1,92 @@ +--- +title: 其他需要注意的宏 +slug: MDN/Structures/Macros/Other +tags: + - Macros + - Reference +--- +<div>{{MDNSidebar}}</div> + +<p>In contrast to the macros listed in <a href="/en-US/docs/MDN/Structures/Macros/Commonly-used_macros">Commonly-used macros</a>, the macros documented in this article are used infrequently or only in specific contexts, or are deprecated.</p> + +<h2 id="Special_contexts">Special contexts</h2> + +<p>These macros are used only with particular contexts, such as a specific API reference.</p> + +<ul> + <li><code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/Interwiki.ejs">Interwiki</a></code> makes it easy to create interwiki links. Currently it supports linking to Wikipedia and Wikimo. The first parameter is the name of the wiki ("wikipedia" or "wikimo"), and the second is the path of the article. For example, <code>\{\{interwiki("wikipedia", "Firefox")\}\}</code> shows up as {{ interwiki("wikipedia", "Firefox") }}. This template auto-detects the page language and directs to the same language on Wikipedia, for example.</li> + <li><code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/RFC.ejs">RFC</a></code> creates a link to the specified RFC, given its number. The syntax is: <code>\{\{RFC(number)\}\}</code>. For example, <code>\{\{RFC(2616)\}\}</code> becomes {{ RFC(2616) }}.</li> + <li>The <code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/anch.ejs">anch</a></code> macro inserts a link to an anchor. <code>\{\{Anch("top")\}\}</code> produces <code><a href="#top">top</a></code> ({{ Anch("top") }}). You can also add a second parameter which contains replacement text to display as the link text.</li> +</ul> + +<h3 id="Landing_page_components">Landing page components</h3> + +<p>We have an assortment of macros that can be used to automatically generate the contents of landing pages. Here they are.</p> + +<h4 id="Lists_of_subpages">Lists of subpages</h4> + +<ul> + <li><code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/ListSubpages.ejs">ListSubpages</a></code> generates an unordered list of links to all the immediate children of the current page; useful for automatically generating tables of contents for sets of documentation.</li> + <li><code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/LandingPageListSubpages.ejs">LandingPageListSubpages</a></code> outputs a two-column definition list of all immediate subpages of the current page, with their titles as the {{HTMLElement("dt")}} and their SEO summary as the {{HTMLElement("dd")}}. This makes it easy to automatically generate reasonably attractive landing pages.</li> + <li><code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/NavListWithPrioritizedPages.ejs">NavListWithPrioritizedPages</a></code> generates an ordered list formatted properly for use in a zone navigation sidebar (or quicklinks). As input, you can specify zero or more page slugs that should be pulled out of the main list and instead inserted at the top of the list, in the given order. All remaining pages are placed in the list alphabetically. One level of subpages is included.</li> + <li><code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/APIListAlpha.ejs">APIListAlpha</a></code> builds a list of the current page's subpages, formatted as a list of API terms, divided up by first letter. There are three parameters. The first is 0 if you want to include all top-level subpages or 1 to leave out subpages with "." in their names. The second and third let you add text to display as part of the name in each link. This can be used to add "<" and ">" for element links, or to add "()" at the end of lists of method names.</li> + <li><code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/SubpagesWithSummaries.ejs">SubpagesWithSummaries</a></code> constructs a definition list of all the immediate children of the current page. There is no other formatting done. You can get a two-column list ready for use as a multi-column landing page using <code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/LandingPageListSubpages.ejs">LandingPageListSubpages</a></code>.</li> +</ul> + +<h3 id="Quicklinks">Quicklinks</h3> + +<p>We have some macros specifically designed to create <a href="/en-US/docs/MDN/Structures/Quicklinks">quicklinks</a>:</p> + +<ul> + <li>The <code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/MakeSimpleQuicklinks.ejs">MakeSimpleQuicklinks</a></code> macro creates a flat list of links in the quicklinks box. Give it a set of paths to destination pages as its input arguments. Each link's text is the page title, and each link has a tooltip derived from the page summary.</li> + <li><code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/QuickLinksWithSubpages.ejs">QuickLinksWithSubpages</a></code> creates a set of quicklinks comprised of the pages below the current page (or specified page, if one is given). Up to two total levels of depth are generated.</li> +</ul> + +<h3 id="Transclusion">Transclusion</h3> + +<p><strong>Transclusion</strong> is the embedding of part or all of one page into another. Exercise caution when using this macro, to ensure that the transcluded content makes sense in the context of the page it is embedded into.</p> + +<p><code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/page.ejs">page</a></code> lets you embed some or all of a specific page into a document. It accepts five parameters:</p> + +<ol> + <li>The URI of the page to transclude. For example, "/en-US/docs/MDN/About".</li> + <li>The name of the section within the page to transclude. This can be specified either as the title string or as the ID of a block to copy over. If not specified, the entire article is transcluded. {{optional_inline}}</li> + <li>The revision number of the page version to transclude. This feature is not currently implemented, but would allow including text from specific versions of an article. {{unimplemented_inline}}</li> + <li>A Boolean value indicating whether or not to show the heading of the top-level section being transcluded. This is useful if you wish to specify your own heading. The default value is false, meaning the heading is not included by default. {{optional_inline}}</li> + <li>The heading level to use as the top heading level. This adjusts the outermost first-discovered level of the transcluded content to the specified number, and all other headings correspondingly. This lets you include content that has its own headings but adjust them to match the heading level at which you're including them. If you don't specify this value, the headings are not adjusted. {{unimplemented_inline}}</li> +</ol> + +<h4 id="Example_without_heading">Example without heading</h4> + +<p>\{{Page("/en-US/docs/MDN/About", "How you can help")}}</p> + +<p>Result:</p> + +<p>{{Page("/en-US/docs/MDN/About", "How you can help")}}</p> + +<h4 id="Example_with_heading">Example with heading</h4> + +<p>\{{Page("/en-US/docs/MDN/About", "How you can help", 0, 1)}}</p> + +<p>Result:</p> + +<p>{{Page("/en-US/docs/MDN/About", "How you can help", 0, 1)}}</p> + +<h2 id="Deprecated">Deprecated</h2> + +<p>These macros have been replace by other ways of doing the same thing, and should no longer be used. If you find them in existing articles, please replace them.</p> + +<h3 id="Linking">Linking</h3> + +<ul> + + <li>The <code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/SectionOnPage.ejs">SectionOnPage</a></code> macro creates a phrase that links to both the name of a section and the article containing that section. For example, <code>\{{SectionOnPage("/en-US/docs/Mozilla/Firefox/Releases/21", "Changes for Web developers")}}</code> outputs the following: <em>{{SectionOnPage("/en-US/docs/Mozilla/Firefox/Releases/21", "Changes for Web developers")}}</em>.</li> + <li>The <code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/manch.ejs">manch</a></code> inserts a link to a method within the current interface; this is intended only for use in interface documentation pages. <code>\{\{manch("foo")\}\}</code> produces <code><code><a href="current/path#foo">foo()</a></code></code> ({{ manch("foo") }}).</li> + <li>The <code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/Link.ejs">Link</a></code> macro inserts a link to the specified page on MDN, using the page's title as the visible string to click on, and the tooltip picked up from the page's SEO summary.</li> + <li>The <code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/LinkItem.ejs">LinkItem</a></code> macro inserts a link to a specified URL, with the indicated text as the visible string to click on. The link automatically picks up as its tooltip the summary of the target page. This differs from <code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/Link.ejs">Link</a></code> in that you must specify the title.</li> + <li>The <code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/LinkItemDL.ejs">LinkItemDL</a></code> macro inserts a link to a specified URL, with the indicated text as a {{HTMLElement("dt")}} which is also the link. The {{HTMLElement("dd")}} element contains the specified page's summary.</li> + <li><code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/funcref.ejs">funcref</a></code> creates links to global functions (usually C++) documented on top-level pages. However, such pages are no longer created at the top-level of MDN.</li> + <li><code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/source.ejs">source</a></code> allows you to link to a Mozilla source code file without having to type a long MXR URL using this syntax: <code>\{\{Source("browser/Makefile.in")\}\}</code>. This gives you: {{ Source("browser/Makefile.in") }}. The text of the link is the path provided; if you want different text, then just provide a second parameter, like so: <code>\{\{Source("browser/Makefile.in", "the browser/ Makefile.in")\}\}</code>, which produces {{ Source("browser/Makefile.in", "the browser/ Makefile.in") }}. Note that the link will be to the very latest version of the file in bleeding-edge code.</li> + <li><code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/Source_cvs.ejs">Source_cvs</a></code> works just like <code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/source.ejs">source</a></code>, except it links to the <a href="/en-US/docs/Mozilla/Developer_guide/Source_Code/CVS">CVS</a> repository instead of the newer <a href="/en-US/docs/Mozilla/Developer_guide/mozilla-central">mozilla-central</a> one.</li> + <li><code><a href="https://github.com/mdn/yari/tree/master/kumascript/macros/LXRSearch.ejs">LXRSearch</a></code> can be used to create an LXR search URL.</li> +</ul> diff --git a/files/zh-cn/mdn/yari/index.html b/files/zh-cn/mdn/yari/index.html index c48e06b138..07b623bec6 100644 --- a/files/zh-cn/mdn/yari/index.html +++ b/files/zh-cn/mdn/yari/index.html @@ -5,7 +5,6 @@ tags: - Yari - Landing - MDN Meta -translation_of: MDN/Yari --- <div>{{MDNSidebar}}</div> diff --git a/files/zh-tw/mdn/yari/index.html b/files/zh-tw/mdn/yari/index.html index 5d3587a166..07b623bec6 100644 --- a/files/zh-tw/mdn/yari/index.html +++ b/files/zh-tw/mdn/yari/index.html @@ -1,27 +1,25 @@ --- -title: 'Kuma: MDN 的維基平台' +title: "Yari: MDN's rendering platform" slug: MDN/Yari tags: - - Kuma + - Yari - Landing - MDN Meta -translation_of: MDN/Kuma -original_slug: MDN/Kuma --- <div>{{MDNSidebar}}</div> -<div>{{IncludeSubnav("/zh-TW/docs/MDN")}}</div> +<p class="summary">Yari is the code that renders MDN Web Docs. It takes a <a href="https://jamstack.org/">JAMStack</a> approach, which involves taking the MDN content stored as flat source files in a GitHub repo (which include front matter and macro calls), rendering them out to static HTML files, and serving those as quickly and efficiently as possible.</p> -<p>Kuma 是由 MDN Web Docs 維護的 Django 程式碼。</p> +<p>The core MDN platform now actually consists of two GitHub repos:</p> -<p>{{SubpagesWithSummaries}}</p> - -<h2 id="參與_Kuma">參與 Kuma</h2> +<ul> + <li><a href="https://github.com/mdn/content">The MDN content repo</a> — this is where the MDN content is stored, along with information such as contributor history and redirects. Visit this repo if you want to contribute to the MDN content.</li> + <li><a href="https://github.com/mdn/yari">The Yari project</a> — this is the platform code that renders and displays the MDN content, and deals with associated services such as user accounts. Visit this repo if you want to contribute to the MDN platform.</li> +</ul> -<p>要參與 Kuma:</p> +<h2 id="See_also">See also</h2> <ul> - <li>訪問一下 <a href="https://github.com/mozilla/kuma">Github 的 Kuma 專案</a>。</li> - <li>去看一下<a href="https://github.com/mozilla/kuma/blob/master/CONTRIBUTING.md">貢獻指引</a>。</li> - <li>需要的話，深入探索<a href="http://kuma.readthedocs.org/en/latest/">Kuma 的完整文件</a>。</li> + <li><a href="https://hacks.mozilla.org/2020/10/mdn-web-docs-evolves-lowdown-on-the-upcoming-new-platform/">MDN Web Docs evolves! Lowdown on the upcoming new platform</a> — explanation of the need for a platform change, and the new architecture.</li> + <li>As needed, take a deep dive into the <a href="https://hacks.mozilla.org/2020/12/welcome-yari-mdn-web-docs-has-a-new-platform/">Welcome Yari: MDN Web Docs has a new platform</a> — formal announcement of the new platform launch.</li> </ul> |