Getting started with Kuma

  • Revision slug: Project:Getting_started_with_Kuma
  • Revision title: Getting started with Kuma
  • Revision id: 378679
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment

Revision Content

{{draft}}

This is an introductory guide to the Kuma wiki platform that powers MDN. "Kuma" is the Japanese word for "bear;" we chose this name because it's a bigger, more powerful creature than Kitsune, the software on which it's based that powers the SUMO web site.

Note: Much of this needs to move into the MDN user guide content, and this isn't necessarily well organized.

Development process

Servers

We have several servers for MDN, based on the state of development of the platform.

Environment URL Purpose
Development https://developer-dev.allizom.org/ Newest features and fixes are added immediately after they pass code review.
Stage https://developer.allizom.org/ Beta features and fixes that will go on the next push to production.
Production https://developer.mozilla.org/ The live MDN server. You're looking at it.

Tracking development

You can see information about recent pushes of code updates to the production server on our Changelog page.

Things that work differently

Redirects

Sometimes you need to have a page that simply redirects to another page, or to a section of another page. This can be needed if a page is merged into another page sometime after its creation, for example. Fortunately, this is easy to do. You can simply click the redirect button in the toolbar, which looks like this:  

The syntax for redirects has changed. You now type the word "REDIRECT" followed by a standard HTML link to the page to redirect to. Switch to source editing mode, then type something like:

REDIRECT <a class="redirect" href="/destination/url/here">some title text here</a>

The URL (href) must be a full path from the base of the site, like "/en-US/docs/foo". Relative URLs will not work. However, you can specify a section within the page using a hashmark ("#") character, such as "/destination/url/here#section_name".

By default, you create links by specifying as the anchor (that is, the part after the hash or "#" symbol) the heading name of the section you want to link to. However, if you're concerned that this might break if headings are changed over time, there's a way to create permanent references for headings. Just add the name attribute to the heading element. Currently you need to do this in the source editor, but in the future we intend to have a user interface for this. Here's an example of what this might look like in the source:

<h2 name="Doing_foo">All about foo</h2>

Now how can link to this section, even if the title's text changes, using \{{anch("Doing foo")}}, or by using "/en-US/path/to/article#Doing_foo" as the link destination.

New features of Kuma

Localization and Translation

KumaScript

See Introduction to KumaScript

Live samples

You can create live samples in Kuma by adding special markup. For example:

<section id="live-sample">
  <pre class="brush: html"><p class="shadow">text-shadow</p></pre>
  <pre class="brush: css">.shadow { text-shadow: 1px 1px 2px black, 0 0 1em blue, 0 0 0.2em blue; }</pre>
  <pre class="brush: js">window.alert("Alert!")</pre>
</section>

Note: You should wrap the code blocks in a non-fragment element - i.e., <section> instead of <ul>

To display the sample live, use an iframe with src of http://page-url$samples/{section_id}. E.g., https://developer.mozilla.org/en-US/docs/Project:Getting_started_with_Kuma$samples/live_samples.

<p class="shadow">text-shadow</p>
.shadow { text-shadow: 1px 1px 2px black, 0 0 1em blue, 0 0 0.2em blue; }
console.log("Alert!")

Note: See the documentation about this in the MDN editor guide for more information about how to use the built-in tools for more easily building live samples.

Finding pages

There are some special search queries you can use to find things:

Search URL Description
https://developer.mozilla.org/admin/wiki/document/?slug__startswith=term Searches for pages whose slug starts with the given term.
https://developer.mozilla.org/admin/wiki/document/?slug__contains=term Searches for pages whose slug contains the given term.

Attachments

You can see a list of all attached files.

Automating and feeds

Kuma offers an an API for retrieving information and (eventually) automatically updating content. See The Kuma API for details.

Additionally, Kuma provides a number of RSS feeds that you can use to monitor the site. See Kuma RSS feeds.

See also

Revision Source

<div>
  {{draft}}</div>
<p>This is an introductory guide to the Kuma wiki platform that powers MDN. "Kuma" is the Japanese word for "bear;" we chose this name because it's a bigger, more powerful creature than Kitsune, the software on which it's based that powers the <a href="https://support.mozilla.org/" title="https://support.mozilla.org/">SUMO</a> web site.</p>
<div class="note">
  <p><strong>Note:</strong> Much of this needs to move into the MDN user guide content, and this isn't necessarily well organized.</p>
</div>
<h2 id="Development_process">Development process</h2>
<h3 id="Servers">Servers</h3>
<p>We have several servers for MDN, based on the state of development of the platform.</p>
<table border="1" cellpadding="1" cellspacing="1" class="standard-table">
  <thead>
    <tr>
      <th scope="col">Environment</th>
      <th scope="col">URL</th>
      <th scope="col">Purpose</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Development</td>
      <td><a class="link-https" href="https://developer-dev.allizom.org/" rel="freelink">https://developer-dev.allizom.org/</a></td>
      <td>Newest features and fixes are added immediately after they pass code review.</td>
    </tr>
    <tr>
      <td>Stage</td>
      <td><a class="link-https" href="https://developer.allizom.org/" rel="freelink">https://developer.allizom.org/</a></td>
      <td>Beta features and fixes that will go on the next push to production.</td>
    </tr>
    <tr>
      <td>Production</td>
      <td><a class="link-https" href="https://developer-new.mozilla.org/" rel="freelink">https://developer.mozilla.org/</a></td>
      <td>The live MDN server. You're looking at it.</td>
    </tr>
  </tbody>
</table>
<h3 id="Tracking_development">Tracking development</h3>
<p>You can see information about recent pushes of code updates to the production server on our <a href="/en-US/docs/Project:Changelog" title="/en-US/docs/Project:Changelog">Changelog page</a>.</p>
<h2 id="Things_that_work_differently">Things that work differently</h2>
<h3 id="Redirects">Redirects</h3>
<p>Sometimes you need to have a page that simply redirects to another page, or to a section of another page. This can be needed if a page is merged into another page sometime after its creation, for example. Fortunately, this is easy to do. You can simply click the redirect button in the toolbar, which looks like this: <span style="background-image: url('https://developer.cdn.mozilla.net/media/ckeditor/skins/kuma/icons.png?t=621afcf'); background-position: 0px -224px;">&nbsp;</span></p>
<p>The syntax for redirects has changed. You now type the word "REDIRECT" followed by a standard HTML link to the page to redirect to. Switch to source editing mode, then type something like:</p>
<pre class="brush:html">
REDIRECT &lt;a class="redirect" href="/destination/url/here"&gt;some title text here&lt;/a&gt;</pre>
<p>The URL (href) must be a full path from the base of the site, like "/en-US/docs/foo". Relative URLs will not work. However, you can specify a section within the page using a hashmark ("#") character, such as "/destination/url/here#section_name".</p>
<h3 id="Creating_link_targets">Creating link targets</h3>
<p>By default, you create links by specifying as the anchor (that is, the part after the hash or "#" symbol) the heading name of the section you want to link to. However, if you're concerned that this might break if headings are changed over time, there's a way to create permanent references for headings. Just add the name attribute to the heading element. Currently you need to do this in the source editor, but in the future we intend to have a user interface for this. Here's an example of what this might look like in the source:</p>
<pre class="brush:html">
&lt;h2 name="Doing_foo"&gt;All about foo&lt;/h2&gt;</pre>
<p>Now how can link to this section, even if the title's text changes, using <code>\{{anch("Doing foo")}}</code>, or by using "/en-US/path/to/article#Doing_foo" as the link destination.</p>
<h2 id="New_features_of_Kuma">New features of Kuma</h2>
<h3 id="Localization_and_Translation">Localization and Translation</h3>
<h3 id="KumaScript">KumaScript</h3>
<p>See <a href="/en-US/docs/Project:Introduction_to_KumaScript" title="Project:Introduction to KumaScript">Introduction to KumaScript</a></p>
<h3 id="Live_samples">Live samples</h3>
<p>You can create live samples in Kuma by adding special markup. For example:</p>
<pre class="brush:html">
&lt;section id="live-sample"&gt;
  &lt;pre class="brush: html"&gt;&lt;p class="shadow"&gt;text-shadow&lt;/p&gt;&lt;/pre&gt;
  &lt;pre class="brush: css"&gt;.shadow { text-shadow: 1px 1px 2px black, 0 0 1em blue, 0 0 0.2em blue; }&lt;/pre&gt;
  &lt;pre class="brush: js"&gt;window.alert("Alert!")&lt;/pre&gt;
&lt;/section&gt;</pre>
<div class="note">
  <p><strong>Note:</strong> You should wrap the code blocks in a non-fragment element - i.e., &lt;section&gt; instead of &lt;ul&gt;</p>
</div>
<p>To display the sample live, use an iframe with src of <code>http://page-url$samples/{section_id}</code>. E.g., <code>https://developer.mozilla.org/en-US/docs/Project:Getting_started_with_Kuma$samples/live_samples</code>.</p>
<section id="sect2">
  <pre class="brush: html">
&lt;p class="shadow"&gt;text-shadow&lt;/p&gt;</pre>
  <pre class="brush: css">
.shadow { text-shadow: 1px 1px 2px black, 0 0 1em blue, 0 0 0.2em blue; }</pre>
  <pre class="brush: js">
console.log("Alert!")</pre>
</section>
<p><iframe src="https://developer.mozilla.org/en-US/docs/Project:Getting_started_with_Kuma$samples/live-sample"></iframe></p>
<div class="note">
  <p><strong>Note:</strong> See <a href="/en-US/docs/Project:MDC_editor_guide#Using_live_sample_code" title="Project:MDC_editor_guide#Using_live_sample_code">the documentation about this in the MDN editor guide</a> for more information about how to use the built-in tools for more easily building live samples.</p>
</div>
<h2 id="Finding_pages">Finding pages</h2>
<p>There are some special search queries you can use to find things:</p>
<table class="standard-table">
  <tbody>
    <tr>
      <th>Search URL</th>
      <th>Description</th>
    </tr>
    <tr>
      <td><code>https://developer.mozilla.org/admin/wiki/document/?slug__startswith=<em>term</em></code></td>
      <td>Searches for pages whose slug starts with the given <em><code>term</code></em>.</td>
    </tr>
    <tr>
      <td><code>https://developer.mozilla.org/admin/wiki/document/?slug__contains=<em>term</em></code></td>
      <td>Searches for pages whose slug contains the given <code>term</code>.</td>
    </tr>
  </tbody>
</table>
<h3 id="Attachments">Attachments</h3>
<p>You can see a list of <a href="/en-US/docs/files" title="/en-US/docs/files">all attached files</a>.</p>
<h2 id="Automating_and_feeds">Automating and feeds</h2>
<p>Kuma offers an an API for retrieving information and (eventually) automatically updating content. See <a href="/en-US/docs/Project:The_Kuma_API" title="Project:The_Kuma_API">The Kuma API</a> for details.</p>
<p>Additionally, Kuma provides a number of RSS feeds that you can use to monitor the site. See <a href="/en-US/docs/Project:Feeds" title="Project:Feeds">Kuma RSS feeds</a>.</p>
<h2 id="See_also">See also</h2>
<ul>
  <li><a href="/en-US/docs/Project:Introduction_to_KumaScript" title="Project:Introduction to KumaScript">Introduction to KumaScript</a></li>
  <li><a href="/en-US/docs/Project:KumaScript_reference" title="Project:en/KumaScript reference">KumaScript reference</a></li>
  <li><a class="link-https" href="https://wiki.mozilla.org/MDN/Kuma" title="https://wiki.mozilla.org/MDN/Kuma">Kuma wiki</a></li>
</ul>
Revert to this revision