Kuma

Kuma: Cool URL tricks

If you’re fiddling with automation, or want to be able to pull information out of the Mozilla Developer Network wiki, there are some helpful queries you can do with URLs that may help you out. Today, I’m going to share those.

The Kuma API

While we don’t yet have a writable API (we know this is a problem, and a design for it is underway), we do have various ways to access useful information about pages in the wiki.

Command Description
?raw Instructs Kuma to return the raw content of the page, without any of the skin material, such as the headers, footers, and so forth. This does not execute templates or scripts. For example, https://developer.mozilla.org/en-US/docs/HTML/HTML5?raw
&macros Instructs Kuma to execute all the templates in the page. For example: https://developer.mozilla.org/en-US/docs/HTML/HTML5?raw&macros
&include Tells Kuma to strip out any blocks that have the class “noinclude” on them. This is useful to get the output as it would appear when included in another page, rather than as a standalone page. Often this will remove sample code and the like (although not always).
&section=[section-id] Instructs Kuma to return the content from only the section with the specified anchor name; for example: https://developer.mozilla.org/en-US/docs/HTML/HTML5?raw&section=Introduction_to_HTML5
$json Tells Kuma to describe the page in a JSON object; this object is essentially the same one you would get using the KumaScript routine wiki.getPage(). For example: https://developer.mozilla.org/en-US/docs/HTML/HTML5$json

These offer a lot of capability, and hopefully will be useful for people building developer tools and other utilities.

Kuma feeds

In addition to the API described above, we also offer a number of feeds. There will likely be more in the future, and some of these are still something of a work in progress, but this information may still be useful for you.

All feeds start with the string “https://developer.mozilla.org/<locale>/docs/feeds/<format>/”, where <locale> is one of the standard locale strings, such as “en-US”, “ja”, and so forth. Note that at present, the locale you specify doesn’t impact the output, but it may eventually do so (indeed, I hope it will). <format> is one of “atom”, “rss”, or “json”.

Feed Description
all All recently changed articles, in order of modification date. This includes newly created articles. All changes are combined into one entry in the feed for each article.
revisions Each revision made to an article, in order by modification date, including newly created articles. Each revision has a separate entry in the feed.
tag/<tagname> Recently changed articles, in order by modification date. Only articles that have the specified tag are included in the feed.
files Recently changed or uploaded files.
needs-review[/<reviewtype>] A list of articles that have the specified review request checked, or all articles with a review requested if you don’t specify a review type. The review type can be one of “tech”, “editorial”, or “kumascript”.

So, for example, you can get an atom format feed of recently changed articles tagged with “JavaScript” thusly: https://developer.mozilla.org/en-US/docs/feeds/atom/tag/JavaScript.

Wrapping up

Hopefully these are useful! There’s more to come, but these are a great start! Enjoy!

View full post on Mozilla Hacks – the Web developer blog

VN:F [1.9.22_1171]
Rating: 0.0/10 (0 votes cast)
VN:F [1.9.22_1171]
Rating: 0 (from 0 votes)

Introduction to Kuma: Templates and scripts

At just after 10 AM today, we switched over from our MindTouch based wiki to our new, Mozilla-built Kuma wiki platform for the Mozilla Developer Network, as I announced yesterday that we’d be doing. So far, all’s well!

Over the next week or two, I will be sharing a few suggestions, tips, and bits of advice about the new platform. This is the first of those posts. Today, I’ll be talking about the new template system.

A little bit of history

When we switched to MindTouch a few years ago, one of the key appeals was their incredibly powerful template system. This system made it possible to write complex scripts to automatically generate content. It could be used for everything from simply styling text to looking up information and generating complicated chunks of material. And over the years we used MindTouch, we grew to rely heavily on it.

A key requirement we had from the beginning was that Kuma support similar capabilities, and as a result, Les Orchard and the rest of our development team built KumaScript, an engine for building exactly this sort of scripting. KumaScript is, in essence, server-side JavaScript implemented using Node.js, with provided additional routines to make it possible to access wiki data and inject material into page content at load time. It has powerful caching in place that make it work incredibly fast, and has proven to be an incredibly useful tool for us.

Introduction to KumaScript

If you’ve done any scripting on MDN in the past, you’ll have to adapt a little bit. Les wrote an excellent guide introducing KumaScript, and I can’t recommend it enough. If you plan to do any scripting, or are curious about the system’s capabilities, read that over.

The truly brilliant thing about KumaScript is that it’s fast and is all JavaScript syntax, so it’s incredibly easy to pick up. If you’ve done any web development, you can script on MDN. The only “trick” is that because it’s so powerful, we do require that you get special privileges to edit or create templates on MDN. You can contact me to get those permissions.

If you’d like to take a look at existing templates to see how they work, there’s a page that lists every template. Look them over and get a feel for things!

About templates that are unconverted

Most of the most-often-used templates have already been converted from MindTouch DekiScript into KumaScript templates. There are some that have not been. Because of this, you may occasionally run into pages that don’t look quite right, or even display a box at the top of the page with an error message. Feel free to ping someone in #devmo about this, or fix it yourself if you have the privileges and the time.

If you’d like to see a list of the templates that are known not to have been updated, there is one! If you update one, please toggle off the “Template review” checkbox at the bottom of the page and add the tag “ks-fixed” to it.

We have spent much of the last few months converting templates, and you shouldn’t run into pages with broken ones very often, but it absolutely can happen.

Key differences you should know about

If you use or write templates, there are a few differences you should know about, other than the obvious syntax differences due to being JavaScript instead of Lua-based.

  • There’s no longer a weird syntax you have to use for templates with a dash (“-”) in their names. You can use them just like any other template: {{foo-bar(“some parameter”)}}.
  • You can’t run KumaScript outside a template like you could with DekiScript. All KumaScript code must be in a template; MindTouch would let you run arbitrary script on any page. For security reasons, we no longer allow this. This does have the side effect of making it no longer possible to nest template calls; you can’t do {{foo(bar())}} like you could in MindTouch.
  • You can use JSON as the only parameter to a template. This gives you a way to create templates that accept, in essence, named parameters.
  • Although we’ve implemented clones of a number of MindTouch APIs as a short-term solution so that we could get online, they should typically not be used by new templates. In addition, only APIs we actually needed have been implemented. From here on out, we will add new Kuma-specific APIs.
  • Templates are heavily cached. The output from a template is saved for every set of inputs it receives. If you change a template, it doesn’t get re-interpreted for a given set of inputs unless someone forces it to be by shift-reloading a page that uses it with those inputs; however, doing this does affect all users, not just you. This vastly improves performance but does mean you have the chance of template changes not being seen by everyone right away.
  • Some locales’ identifier codes have changed.
  • URL paths have changed: instead of /en/JavaScript, for example, it’s now “/en-US/docs/JavaScript”. Server rewrite rules are in place to automatically redirect existing links, but new templates should do it the new way.
  • You can’t apply a “nowiki” or “plain” class to text to keep it from being interpreted as a template anymore. Instead, add a backslash in front of the first “{” in the template invocation. This is useful when editing docs about templates, for instance.

Give it a try!

That’s a quick overview of what KumaScript is and what’s different about it. There’s certainly a lot more to discover, so be sure to read the Introduction to KumaScript and feel free to ask for help on IRC if you need it!

View full post on Mozilla Hacks – the Web developer blog

VN:F [1.9.22_1171]
Rating: 0.0/10 (0 votes cast)
VN:F [1.9.22_1171]
Rating: 0 (from 0 votes)

It’s time: MDN relaunch on Kuma wiki on August 3

That’s right! We’re finally ready to throw the switch! Tomorrow (that is, Friday, August 3, 2012) we intend to switch from the current MindTouch-based wiki to our new Kuma platform for the Mozilla Developer Network wiki. The changeover should happen at about 10:00 AM Pacific Daylight Time.

At that time, there should be, at most, a few moments of downtime, then the site should be running on the new system.

A few things you might need to know:

  1. There’s lots more stuff we’re planning to do to make Kuma even better than it already is. You may even notice some stuff that isn’t done yet. However, weeks and weeks of testing have told us that it works very well, so we decided it was time to go ahead and launch.
  2. We have updated documentation for using the wiki that you might like to look over, as well as an updated Editor guide.
  3. Things are different! You will run into stuff that doesn’t work the way you’re used to. It should look pretty familiar, by and large, though, and most people won’t notice the changes unless they look closely.
  4. There’s a big “Report a bug” button at the top-right corner of the window. Please use it! Any time you have a problem, concern, see something that looks wrong, or have an idea for a brilliant way to improve the system, click it and follow the handy wizard that will help you file your bug. We want the MDN wiki to rock, and you can help make it so.

We will be sharing additional information about where we are and where things are going over the next week or two, and, of course, for the foreseeable future as we continue development. Indeed, the MDN development team is getting together for a week of meetings next week to rehash processes and sort out priorities for what to work on next.

View full post on Mozilla Hacks – the Web developer blog

VN:F [1.9.22_1171]
Rating: 0.0/10 (0 votes cast)
VN:F [1.9.22_1171]
Rating: 0 (from 0 votes)

Kuma: The updated editor experience

The editing experience on the new Kuma wiki that we’ll be deploying starting on July 5th is not enormously different from what you’re used to, but there are some key differences I’d like to call out.

Getting into the editor

Let’s take a look, first, at differences in how you get into the editor. Once you’ve logged in using BrowserID, you’ll still see your old friend, the “Edit” button, at the top right corner as usual:

Screenshot of primary edit buttonYou can simply click that big blue “Edit” button to begin editing the entire page. Easy! But if you want, you can edit just a single section. Each header line has its own edit button off to the right, like this:

Screenshot of the section editing button.

Clicking that pretty blue “Edit” button to the right of the section heading will open an editor just for that section.

Changing page information

Once you’re in the editor, you can edit both content and page information. At the top left you see the title of the page:

Screen shot of the heading box.

Clicking on the “i” icon gives you access to edit page metadata:

Screen shot of the metadata editor.

You can then edit the page’s title (that is, the text displayed as the title of the individual page, and the slug, which is the URL component below the parent page (which you can’t edit; there’s a separate move feature for that).

The “TOC” checkbox lets you toggle whether or not the page displays its table of contents of its headers.

Saving and previewing

Then, at the top right of the editor screen, you’ll see these buttons:

Screen shot of the bar of save/discard options.

These are pretty self-explanatory. The first gives you the option to save your changes without leaving the editor; this is a feature we’ve wanted for ages, but finally have. The second button saves your changes and closes the editor.

The “Preview Changes” button actually opens a new tab showing a preview of the page. We finally, finally, have the ability to double-check our use of scripted templates before saving your edits. This is a huge deal for us!

Finally, the “Discard Changes” button lets you throw away your edits. Hopefully that’s pretty obvious.

Editing

The editor is essentially the same CKEditor we’ve always used on MDN, although it’s a newer version. Most of our keyboard shortcuts are the same as they were before. The most notable difference is that Ctrl-S no longer toggles source mode; instead, it does a “Save Changes.”

One thing we’ve done is revamp the toolbar to be more useful for the types of work we do:

Screen shot of the MDN editor's toolbar.

This is very reorganized from what we had before, with fewer unneeded buttons. Immediately below the toolbar is a block hierarchy bar; this shows you the hierarchy of elements that leads to your current cursor position. This is helpful, for example, to know what heading level you’re on, or how deeply nested your list is, and so forth.

We also now have handy buttons for the heading levels, and a button for preformatted text. To the right of the <pre> button is a menu that, when opened while your cursor is in a <pre> block, presents a list of syntax highlighting language options:

Screen shot of the MDN syntax highlighting popup.

This list is much simpler than the old one, and is certainly easier to read!

The style drop-down menu is pretty similar to the old one, with an assortment of styles we use regularly:

Screen shot of the styles drop-down menu.Tagging articles

Currently, the only way to tag articles is from within the editor screen. This will be changed at some point, but for now, you will find the tag editor at the bottom of the edit page:

Screen shot of the MDN tag editor.

You can delete tags by clicking the “X” in each tag’s box, or add new ones by simply clicking to the right of the tag list and starting to type.

There’s currently a bug that makes it impossible to enter tag names with spaces in their names. This will hopefully be fixed before we deploy Kuma.

Requesting reviews

We’re in the process of building a new, formal review system. While not all of the support for tracking reviews is in place yet, you can establish review requests using the checkboxes at the bottom of the editor page:

Screen shot of the review checkboxes.

For new articles, both the technical and editorial review requests are enabled by default. You can set or clear these as appropriate based on the type and number of changes you’ve made (and, of course, your confidence in your work!).

The “Template” review request is used to indicate that a template has been changed and needs a code review. This won’t affect very many people, because template editing is now under a tighter set of permissions than most editing, for security reasons.

Onward and upward

We will continue to iterate on the editing experience going forward, to make it even better. There are lots of things we want to do to make Kuma amazing!

Sometime in the next couple of days, I’ll share a look at the new localization tools we provide in Kuma. They’re not finished, but they’re already much, much better than what we had with our old system (which is to say: none at all).

View full post on Mozilla Hacks – the Web developer blog

VN:F [1.9.22_1171]
Rating: 0.0/10 (0 votes cast)
VN:F [1.9.22_1171]
Rating: 0 (from 0 votes)

MDN: The Kuma switch begins on July 5th!

Hopefully by now you’re aware we’re switching to a brand new, Mozilla-built wiki platform for the Mozilla Developer Network. The new site will launch in mid-July, and we’re incredibly excited about it!

As part of the launch process, we’re going to begin directing all editing of content to the new wiki starting on July 5th. That means any time someone tries to edit a page, they will actually go to the new site and edit that instead. No editing of the current, MindTouch powered site will be possible from that time on.

The current site will remain in place for the time being, and viewers will see that rather than the updated content. However, each page will include a banner explaining the situation and offering a link to the equivalent page on the new wiki, for people that want to view the very latest content.

On the weekend of July 7-8, we plan to have a very structured test program, led by Mozilla’s brilliant QA team. We will be inviting community members to participate actively, to help ensure that the new site is ready for action.

We continue to expect to launch the new site on or around July 15th, directing all traffic there.

Watch this space for further announcements. We’re getting close now, and we’ll need your help to get there!

View full post on Mozilla Hacks – the Web developer blog

VN:F [1.9.22_1171]
Rating: 0.0/10 (0 votes cast)
VN:F [1.9.22_1171]
Rating: 0 (from 0 votes)