Bạn sẽ sử dụng các bố cục sau xuyên suốt tài liệu của mình để chỉ định các phần và phần phụ của nội dung

Tiêu đề phần chính

Nội dung phần chính

l-phần-chính h2 Phần Tiêu đề p phần nội dung

Tiêu đề tiểu mục

nội dung phần phụ. Nội dung này có liên quan đến nội dung phần chính và nằm trong phần chính

l-sub-section h3 Sub Section Title p sub section content

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

include . /_util-fns

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

+makeExample('styleguide/js/src/index. html', null, 'index. html')

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

Documentation Style foo2

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

+makeTabs('styleguide/js/src/index. html, styleguide/js/spec. js', null, 'index. html,unit test')

This will create two tabs, each with its own title and appropriately color coded

Documentation Style foo2 describe("Jasmine sample test", function() { it("1+1 should be 2", function() { var result = 1 + 1; expect(result).toBe(2); }); });

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 .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 crucifix5. Following this a second string that is the 'name' of the region is also allowed but not required. Một tệp có thể có bất kỳ số lượng .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 crucifix5 nhận xét nào với yêu cầu duy nhất là tên của từng khu vực trong một tệp phải là duy nhất. Điều này cũng có nghĩa là chỉ có thể có một vùng tài liệu trống

Example of a simple #docregion

// #docregion describe("Jasmine sample test", function() { it("1+1 should be 2", function() { var result = 1 + 1; expect(result). toBe(2);

Nếu một tệp chỉ có một .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 crucifix5 thì toàn bộ tệp SAU KHI nhận xét .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 crucifix5 sẽ có sẵn để đưa vào qua mixin. Các phần của tệp có thể được chỉ định bằng cách bao quanh một khu vực của tệp bằng thẻ .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 crucifix5 và thẻ table tr th Framework th Task th Speed tr td AngularJS v.1.3 td Routing td fast0. 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

(function() { // #docregion // #docregion class-w-annotations var AppComponent = ng // #docregion component . Component({ selector. 'my-app', // #enddocregion component // #docregion view template. 'Ứng dụng góc đầu tiên của tôi' }) // chế độ xem #enddocregion // lớp #docregion. Class({ constructor. function () { } }); // #enddocregion // #enddocregion

Multiple .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 crucifix5 tags may be defined on a single line as shown below. In addition, anytime a file contains multiple .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 crucifix5 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 table tr th Framework th Task th Speed tr td AngularJS v.1.3 td Routing td fast5 comment as shown below. This example creates a separator that consists of table tr th Framework th Task th Speed tr td AngularJS v.1.3 td Routing td fast6 in the output file

// #docplaster more code here // #docregion import,twoparts import { Component } from '@angular/core'; import { bootstrap } from '@angular/platform-browser-dynamic'; // #enddocregion twoparts, import @Component({ selector. 'my-app', template. 'My first Angular App' }) class AppComponent { } // #docregion bootstrap, twoparts bootstrap(AppComponent); // #enddocregion twoparts doSomethingInteresting(); // #enddocregion

HTML files can also contain #docregion comments

.

as can CSS files

/* #docregion center-global */ . center-global { max-width. 1020px; margin. 0 auto; }

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' .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 crucifix5 you will pass the name of the desired region as the 2nd parameter to the makeExample call

Example

+makeExample('styleguide/js/src/app. js', 'class-w-annotations', "Extracted region")

is a request to include just the table tr th Framework th Task th Speed tr td AngularJS v.1.3 td Routing td fast8 region from the table tr th Framework th Task th Speed tr td AngularJS v.1.3 td Routing td fast9 file in the 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.0 folder and results in the following

Extracted region

app.AppComponent = ng.core.Component({ selector: 'my-app', template: '

My First Angular App

' }) .Class({ constructor: function () { } });

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 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.1 and 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.2 parameters in the makeExample and makeTabs mixins. A 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.1 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

+makeExample('styleguide/js/src/index. html', null, 'index. html', {pnk. /script (src=. *")/g})

Which will mark all of the quoted contents of each 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.6 tag within the index. html file in pink

Note that expression replacement occurs AFTER the fragment has been included and html escaped. This means that your regular expression must use escaped html text; i. e. the '"' in the regex above

src/index. html

Documentation Style foo2 src="node_modules/core-js/client/shim.min.js"> foo2

A more complicated example might be

- var stylePattern = { pnk. /script (src=. *")/g, otl. /(\S*my-app. *$)/m }; +makeExample('styleguide/js/src/index. html', null, 'index. html', stylePattern )

Which applies multiple styles and uses an intermediate javascript object as opposed to a literal

index. html

Documentation Style foo2