Guides

To include guides use the --guides option to specify a path to a JSON file with the following structure:

    [
        {
            "title": "Ext JS 4 Guides",
            "items": [
                {
                    "name": "getting_started",
                    "url": "guides/getting_started",
                    "title": "Getting Started with Ext JS 4",
                    "description": "This introduction to Ext JS 4 explains how you can get started."
                },
                {
                    "name": "class_system",
                    "url": "guides/class_system",
                    "title": "The Class System",
                    "description": "Creating classes with the new class system in Ext JS 4.x."
                },
                {
                    "name": "custom_url",
                    "url": "guides/custom_file.md",
                    "title": "The Class System",
                    "description": "Creating classes with the new class system in Ext JS 4.x."
                },
                {
                    "title": "Subgroup of guides",
                    "items": [
                        ...
                    ]
                }
                ...
            ]
        },
        ...
    ]

Each guide directory might contain a README.md file that contains the guide in Markdown format. For icon and other images, read further below. If you define the guide file path in the url then you can have a custom name for the guide file.

Here's an example directory structure for the above guides.json:

somedir/
    guides.json
    guides/
        getting_started/
            README.md
            icon.png
            some-image.png
        class_system/
            README.md
            icon.png
            example.zip
        custom_file.md

Each guide must have a unique name. But the url field is not required - when it's not specified it will default to guides/<name>, e.g. in the case of the above example the url could be safely left out.

Formatting

Here's an example of how the guide should be formatted and structured:

# My Example guide

A guide about blah blah blah...

## First subsection

More text...

### A sub-subsection

- some
- bulleted
- list

## Second subsection

Even more text...

    @example
    function foo() {
        // live code example
    }

A guide must begin with a <h1> heading. That heading will be specially formatted when guide is shown. Normally that's the same as the "title" of the guide given in guides config JSON file.

All following headings must be <h2> or below. The <h2> headings will be used to generate a table of contents of the guide (it will only get created if there are at least two <h2> headings.

Style guide

The following is just recommendation, not a strict requirement.

Use the ###... style markup for headings instead of the underlined headings, as you need to use that style anyway if you want <h3> headings and beyond, plus it's harder for somebody who doesn't know Markdown syntax by heart, to tell the difference between <h1> and <h2> heading in the underlined markup. And just add the # chars at the beginning of line, don't repeat them at the end - keep it DRY.

Leave a blank line between the heading and text that follows - it will keep the markup more readable when one doesn't have editor with Markdown syntax highlighting.

Don't number your headings. The <h2> headings will get numbered in the generated table of contents anyway, so if you add your own numbers, the result will look silly and sloppy.

Don't write excessively long lines, relying on the line-wrapping of your editor. Instead wrap the lines manually like you do when writing comments in normal source code. This way it'll work much better with source control, making the diff much more useful and pleasant to read.

Icon

If guide directory contains an icon.png file, it will be used as an icon for the guide in guides index page (otherwise a default icon will be used).

Images

Guide-related images can be placed directly inside the guide directory and linked with and {@img} tag:

{@img some-image.png Alt text}

One can also use the Markdown image syntax to include images from any URL:

![Alt text](http://example.com/logo.png)

But {@img} tag should be preferred for local images as JSDuck will warn you about missing images referenced that way, while the Markdown image references aren't checked at all.

Links

To reference API classes and members use the {@link} tag as you would inside API docs:

See {@link Ext.Panel#title title} config for details.

To link chapters and arbitrary anchors within a guide use simple #hashfragment links:

## Getting started

Some intro text in here...

See the [next chapter](#next-steps), especially the [first step](#first).

## Next steps

Here you go:

- <a name="first">The first step is to...</a>

All chapter titles are automatically assigned ID-s calculated using the formula: title.toLowerCase().replace(/\W+/, "-")

To link other guides, use Markdown links in the form of:

Check out [Class System Guide](#!/guide/class_system) for additional reading.

To link a section of a another guide include the hashfragment part separated with -section-:

See the [Getting started in Class system guide](#!/guide/class_system-section-getting-started).

Examples and videos can be linked in a similar fashion.

For all other links, also use normal Markdown links. See the next section for linking to resources inside guide directory.

Other resources

You can include any other files inside the guide directory, and all of these will be copied over into JSDuck output directory.

But to link those resources, you need to use Markdown links with URL-s in form of guides/<guide-name>/<your-file>. For example:

[Download MVC example](guides/class_system/example.zip)