Basic Layouts
You will use the following layouts throughout your documentation to specify sections and sub-sections of content.
Main Section Title
Main section content...
Sub Section Title
sub section content... This content is related to the main section content and falls within the main section.
Code Examples
Below are some examples of how you can add/customize code examples in a page.
Including a code example from the _examples folder
One of the design goals for this documentation was that any code samples that appear within the documentation be 'testable'. In practice this means that a set of standalone testable examples exist somewhere in the same repository as the rest of the documentation. These examples will each typically consist of a collection of html, javascript and css files.
Clearly there also needs to be some mechanism for including fragments of these files into the jade/harp generated
html. By convention all of the 'testable' examples within this repository should be created within the docs/_examples folder.
To include an example from somewhere in the doc/_examples folder you can use the makeExample mixin.
This mixin along with the makeTabs mixin both require that the 'included' file be marked
up with special comment markers. This markup will be described a bit later.
In addition there are several custom gulp tasks that must be run before any of the edits described below will actually appear in the generated documentation. These gulp tasks are documented elsewhere.
In order to use the makeExample or makeTabs mixins each page that references the mixins must include the '_utilFns.jade'
file on the current page. This is usually accomplished simply by adding a path to this file at the top of any
page that needs either of these mixins.
The syntax for the makeExample mixin is:
+makeExample(filePath, region, title, stylePattern)
- filePath: path to the example file under the '_examples' folder
- region: (optional or null) region from the example file to display
- title: (optional or null) title displayed above the included text.
- stylePattern: (optional or null) allows additional styling via regular expression ( described later).
Example:
This will read the _examples/styleguide/js/src/index.html file and include it with the heading 'index.html'. Note that the file will be properly escaped and color coded according to the extension on the file ( html in this case).
index.html
The second parameter with a value of 'null' will be described later in this document.
There is a similar makeTabs mixin that provides the same service but for multiple examples
within a tabbed interface.
+makeTabs(filePaths, regions, titles, stylePatterns)
- filePaths: a comma delimited string of filePaths to example files under the '_examples' folder
- regions: (optional or null) region from the example file to display
- titles: (optional or null) a comma delimited string of titles corresponding to each of the filePaths above.
- stylePatterns: (optional or null) allows additional styling via regular expression( described later).
Example:
This will create two tabs, each with its own title and appropriately color coded.
Marking up an example file for use by the makeExample and makeTabs mixins
At a minimum, marking up an example file simply consists of adding a single comment line to the top of the file
containing the string #docregion. Following this a second string that is the 'name' of the region is also allowed
but not required. A file may have any number of #docregion comments with the only requirement being that the names
of each region within a single file be unique. This also means that there can only be one blank docregion.
Example of a simple #docregion
If a file only has a single #docregion then the entire file AFTER the #docregion comment is available for inclusion
via mixin. Portions of the file can be indicated by surrounding an area of the file with
#docregion and an #enddocregion tags. These regions, each with its own name, may be nested to any level and any regions that are not 'ended' explicitly
are assumed to be ended automatically at the bottom of the file. Regions may either be ended/closed by name or if the name is left blank then the most recent
unclosed docregion defined earlier will be closed. Any individual region within the file is accessible
to the makeExample and makeTabs mixins.
Example of a nested #docregion
My First Angular App
' }) // #enddocregion view // #docregion class .Class({ constructor: function () { } }); // #enddocregion // #enddocregionMultiple #docregion tags may be defined on a single line as shown below. In addition, anytime a file contains multiple
#docregion tags with the same name they will automatically be combined. Each of the individually tagged sections of the combined document
will be separated from one another by a comment consisting of '. . .'. This default separator, known
as 'plaster' can be overridden anywhere within the affected file via a #docplaster comment as shown below. This example creates
a separator that consists of /* more code here */ in the output file.
My first Angular App
' }) class AppComponent { } // #docregion bootstrap, twoparts bootstrap(AppComponent); // #enddocregion twoparts doSomethingInteresting(); // #enddocregionHTML files can also contain #docregion comments:
as can CSS files:
Including a named #docregion via the makeExample or makeTabs mixins.
In order to include just a portion of an example file that has been marked up with a 'named' #docregion
you will pass the name of the desired region as the 2nd parameter to the makeExample call.
Example
is a request to include just the class-w-annotations region from the app.js file in the _examples/styleguide
folder and results in the following:
Extracted region
Additional styling
In some cases you may want to add additional styling to an external file after it had been included in the documentation.
This styling is accomplished via the stylePattern and stylePatterns parameters in the makeExample and makeTabs
mixins. A stylePattern is actually just a javascript object where the keys are the names of styles to be applied to
some portion of the included text as defined by a regular expression ( or expressions). These regular expressions are the
value of each key. Each regular expression MUST specify at least a single capture group; the contents of the capture
group being what the style will actually apply to, not the entire regular expression. The idea here is that you may
need to include a contextual match in a regular expression but only want your styling to be applied to a subset
of the entire regular expression.
Current there are only three types of highlight styles available: Outlined (otl), Pink (pnk), and Black (blk), however the mechanism described above will work with any style defined on the page.
Example
Which will mark all of the quoted contents of each script tag within the index.html file in pink.
src/index.html
A more complicated example might be:
Which applies multiple styles and uses an intermediate javascript object as opposed to a literal.
index.html
makeTabs support for stylePatterns is slightly different from the makeExample mixin in that you can also
pass in an array of stylePattern objects where each is paired with its corresponding 'tab'. If only a single stylePattern
object is passed in then it is assumed to apply to all of the tabs.
Including a JSON file or just parts of one
To include an '.json' file from somewhere in the doc\_examples folder you can use the makeJson mixin. The makeExample
and makeTabs mixins cannot be used for this purpose because there is no standard 'comment' marker in a json file.
The makeJson mixin does however provide a similar capability to selectively pick which portions of the '.json' file
to display.
The syntax for the makeJson mixin is:
+makeJson(filePath, jsonConfig, title, stylePattern)
- filePath: path to the example file under the '_examples' folder
- jsonConfig: (optional) an object that defines which portions of the .json file to select for display.
- rootPath: (optional default=null) a json property path at which the 'paths' parameter below should start.
- paths: a comma delimited list of property paths for those elements to be selected.
- space: (optional default=" " [2 spaces]) a String or Number object that's used to insert white space into the output JSON
- title: (optional) title displayed above the included text.
- stylePattern: (optional) allows additional styling via regular expression ( described above).
Example:
Entire package.json file
A subset of the '.json' file can also be selected.
Selected parts of the package.json file
Styling selected portions of the json is also supported.
package.json dependencies
As well as styling across multiple lines.
Foo
Inline code and code examples provided directly i.e. not from an example file.
The makeExample and makeTabs mixins are both both built on top of a custom jade 'style'; code-example.
In those cases where you want to include code directly inline i.e. not from some external file; you can use
this style.
This style has several named attributes
code-example attributes
- name: Name displayed in Tab (required for tabs)
- language: javascript, html, etc.
- escape: html (escapes html, woot!)
- format: linenums (or linenums:4 specify starting line)
Example
Specify starting line number
Specify a language
Prettify makes a best effort to guess the language but works best with C-like and HTML-like languages. For others, there are special language handlers that are chosen based on language hints. Add a class that matches your desired language (example below uses .lang-html)
Code Highlighting
There are three types of highlights available Outlined, Pink, and Black. You can see examples below and the class names needed for each type.
Code Tabs
Code Tabs are a great way to show different languages and versions of a particular piece of code. When using these tabs make sure the content is always related.
To create code tabs simply use the directives below
Combining makeExample, makeTabs mixins with code-example style attributes
As mentioned above the makeExample and makeTabs mixins are built on top of the code-example style. By default
the mixins automatically determine a language based on the example file's extensions and always include line numbers.
You can override this behavior by including code-example attributes within parentheses after the mixin parameters.
Example
Starts the numbering of the example at line 15.
Or to suppress line numbering completely you can use
Code examples in angular/angular source code
References to embedded example code in the angular/angular source make use of the same mixins as defined above, but with a slightly different syntax. Inline tags in source code comments like {@example ...} and {@exampleTabs ...} actually generate 'makeExample' and 'makeTabs' mixins calls in the documentation. The order of 'arguments' in the inline tags is also the same as that of the mixins defined above. However, optional parameters can also be specified via name (optionally prefixed with a '-'), as will be shown by example below. Parameters that include spaces should be enclosed in either single or double quotes. This syntax is intended to mirror standard command line argument patterns.
@example inline tag parameters
- filePath: path to the example file under the '_examples' folder
- region: (optional or null) region from the example file to display
- title: (optional or null) title displayed above the included text.
- stylePattern: (optional or null) allows additional styling via regular expression ( described later).
Examples
@exampleTabs inline tag parameters
- filePaths: a comma delimited string of filePaths to example files under the '_examples' folder
- regions: (optional or null) region from the example file to display
- titles: (optional or null) a comma delimited string of titles corresponding to each of the filePaths above.
- stylePatterns: (optional or null) allows additional styling via regular expression( described later).
Examples
Cross references to Developer guide pages in angular/angular source comments.
The '{@linkDevGuide ... }' inline tag is intended to be used to create links from api documentation to dev guide documentation.
@linkDevGuide inline tag parameters
- filePath: a filePath that points to a jade page in the DevGuide without the .jade extension ( under public/docs ).
- title: The title of link. If the title is omitted an attempt will be made to determine the title of the jade page
being pointed to. If not found the then title will simply be the link.
Examples
Alerts
Please use alerts sparingly throughout the docs. They are meant to draw attention on important occasions. Alerts should not be used for multi-line content (user callouts insteads) or stacked on top of each other.
Adding an alert
.alert.is-critical A very critical alert
.alert.is-important A very important alert
.alert.is-helpful A very helpful alertCallouts
Please use callouts sparingly throughout the docs. Callouts (like alerts) are meant to draw attention on important occasions. Unlike alerts, callouts are designed to display multi-line content.
Adding a Callout
Pitchfork hoodie semiotics, roof party pop-up paleo messenger bag cred Carles tousled Truffaut yr. Semiotics viral freegan VHS, Shoreditch disrupt McSweeney's. Intelligentsia kale chips Vice four dollar toast, Schlitz crucifix
A vePitchfork hoodie semiotics, roof party pop-up paleo messenger bag cred Carles tousled Truffaut yr. Semiotics viral freegan VHS, Shoreditch disrupt McSweeney's. Intelligentsia kale chips Vice four dollar toast, Schlitz crucifix
Pitchfork hoodie semiotics, roof party pop-up paleo messenger bag cred Carles tousled Truffaut yr. Semiotics viral freegan VHS, Shoreditch disrupt McSweeney's. Intelligentsia kale chips Vice four dollar toast, Schlitz crucifix
.callout.is-critical
header A Critical Title
p Pitchfork hoodie semiotics, roof party pop-up paleo messenger bag cred Carles tousled Truffaut yr. Semiotics viral freegan VHS, Shoreditch disrupt McSweeney's. Intelligentsia kale chips Vice four dollar toast, Schlitz crucifix
.callout.is-important
header A Very Important Title
p A vePitchfork hoodie semiotics, roof party pop-up paleo messenger bag cred Carles tousled Truffaut yr. Semiotics viral freegan VHS, Shoreditch disrupt McSweeney's. Intelligentsia kale chips Vice four dollar toast, Schlitz crucifix
.callout.is-helpful
header A Very Helpful Title
p Pitchfork hoodie semiotics, roof party pop-up paleo messenger bag cred Carles tousled Truffaut yr. Semiotics viral freegan VHS, Shoreditch disrupt McSweeney's. Intelligentsia kale chips Vice four dollar toast, Schlitz crucifixTables
Tables can be used to present tabular data as it relates to each other.
Adding an table
| Framework | Task | Speed |
|---|---|---|
| AngularJS v.1.3 | Routing | fast |
| AngularJS v.1.4 | Routing | faster |
| Angular | Routing | fastest :) |
table
tr
th Framework
th Task
th Speed
tr
td AngularJS v.1.3
td Routing
td fastAsides
You this for content that is related in a tangential way but not critical to learning, it can be ignored. The paragraph that includes this element should always surround it with text.
Adding an aside
Etsy artisan Thundercats, authentic sustainable bitters wolf roof party meditation 90's asymmetrical XOXO hoodie. Twee umami cray iPhone. Chillwave shabby chic tilde occupy sriracha squid Brooklyn street art. Selvage heirloom kogi American Apparel bicycle rights. Carles Etsy Truffaut mlkshk trust fund. Jean shorts fashion axe Williamsburg wolf cardigan beard, twee blog locavore organic. Cred skateboard dreamcatcher, taxidermy Bushwick actually aesthetic normcore fanny pack.
aside.is-right Did you know that hipsum is a replacement for Lorem Ipsum? To find out more visit hipsum.co
p.
Etsy artisan Thundercats, authentic sustainable bitters
wolf roof party meditation 90's asymmetrical XOXO hoodie.
Twee umami cray iPhone. Chillwave shabby chic tilde
occupy sriracha squid Brooklyn street art.Images
To maintain visual consistency across documentation chapters, please follow the best practices for authors outlined in the Image Guide.
The browser background template used for outlining screenshots is here.