Migrating Guides to DocPad

The following are the basic steps for migrating a guide from the old Guides tool (ruby-based) to the new DocPad tool (javascript/node). If you have any questions, just ask on IRC!

Setup

• Find the issue for the guide you would like to convert.

• Assign it to yourself.

• Open the .textile file of the guide. The easiest way is to visit https://github.com/sproutcore/guides/tree/master/source, click the appropriate guide and then click the "Edit" button at the top right.

• Copy the entire Textile document and paste it into a new document in the docpad-guides branch with the same name as the existing Textile document but change the extension from .textile to .html.md.sd.

Migrating the Syntax

• Copy the header from an existing guide and modify it to match everything before the endprologue. statement. This includes the page title, description (if provided) and list (if provided).

• Update the sc_category attribute to match the category on the existing site (just use the heading it is under in the Guides index dropdown such as Start Here or Theming).

• Leave the sc_order as-is, it will be updated by the reviewer that accepts your pull request.

• Find and replace all of the headers (h1., h2., etc) with the same number of # characters. For instance, an h2. should be replaced with ##.

• Scroll through the content and fix all links to match the Markdown syntax

• Update all code examples to use the following format:

      ```codetype
      # filename=/some/cool/place
      code = 'something'
      if (example) {
       do cool stuff
      }
      ```

  For instance

      ```javascript
      # filename=apps/my_cool_app/core.js
      var a = 13;
  
      if (a > 12) {
        console.log("a is pretty big!");
      }
      ```

• Fix paragraphs so that no line is greater than about 80 characters. This is not a hard/fast rule, but it helps readability. In general, you do NOT need to do this with code examples (this can be done easily in Vim by going to the line in escape mode and typing gqq). NOTE: This does not apply to the header since multiple lines actually breaks the header onto multiple lines.

• Fix any incorrect lists.