UNPKG

3.89 kBMarkdownView Raw
1
2Firedoc Themes
3--------------
4
5## Commands
6
7The following commands let you can manage firedoc themes locally.
8
9#### Install
10
11```
12firedoc-theme install url [--name name]
13```
14
15#### Uninstall
16
17```
18firedoc-theme uninstall [name]
19```
20
21#### Clear
22
23```
24firedoc-theme clear
25```
26
27## How to create a theme for firedoc
28
29#### Distrubution
30
31The complete firedoc theme distrubution should be the below:
32
33```
34themes/default/
35├── assets
36│   ├── css
37│   ├── favicon.png
38│   ├── img
39│   ├── index.html
40│   ├── js
41│   └── vendor
42├── i18n
43│   ├── en.json
44│   └── zh.json
45├── layouts
46│   ├── main.handlebars
47│   └── xhr.handlebars
48├── partials
49│   ├── attrs.handlebars
50│   ├── class-tree.handlebars
51│   ├── classes.handlebars
52│   ├── enums.handlebars
53│   ├── events.handlebars
54│   ├── files.handlebars
55│   ├── index.handlebars
56│   ├── items-index.handlebars
57│   ├── method.handlebars
58│   ├── module.handlebars
59│   ├── options.handlebars
60│   ├── props.handlebars
61│   └── sidebar.handlebars
62├── locals.js
63└── theme.json
64```
65
66The next, we will walk them as detailed as possible.
67
681. The directory "layouts" stores the skelton layout file.
692. The directory "partials" stores the detailed templates for `modules`, `classes` and other templates used by the former.
703. The directory "assets" stores the static resources like scripts, css files and fonts.
714. The directory "i18n" stores the i18n resources for templates, naming as `{lang}.json`.
725. The file `locals.js` is used to support a programable for theme developer, it is expected to export a function, which could rewrite the locals for templates variables.
73
74#### Template Context
75
76By default, all templates should have the ability to access to the following variables in his template context:
77
78```
79{
80 globals: {
81 classes: [ /* all classes */ ],
82 modules: [ /* all modules */ ]
83 },
84 i18n: {
85 /* Just for i18n templates object
86 }
87}
88```
89
90But as in some special templates, the firedoc would make some shortcuts for the corresponding template:
91
92- `module`: the `module` template would be directly called at firedoc itself to generate `modules/*.html` to `dest` path, so that to simplify this spec, firedoc attaches the corresponding `module` object to the current context.
93- `classes`: the `classes` template would be directly called at firedoc itself to generate `classes/*.html` to `dest` path, so that to simplify this spec, firedoc attaches the corresponding `class` object to the current context.
94
95#### Use i18n
96
97The i18n in firedoc theme template just looks like add a map variable `i18n` into template `locals`, and the firedoc will depends on the `--lang` option's value to decide what file under `i18n` would be used. The complete example are at [themes/default](default/i18n).
98
99At template, we just can use i18n map by the below super simple way:
100
101```html
102<p>{{i18n.EXAMPLE_I18N_TEXT}}</p>
103```
104
105#### Programable Theme
106
107Sometimes, theme-maker might want a way to implement a new feature without any help from firedoc, so the `locals.js` would help the themer. Here is an example:
108
109```js
110module.exports = function (modules, classes, locals) {
111 // TODO
112};
113```
114
115Then you could work with `modules`, `classes` and `locals` that you want, like if you want to add a timestamp for all classes:
116
117```js
118module.exports = function (modules, _, _) {
119 modules.forEach(function (mod) {
120 mod.timestamp = Date.now();
121 });
122}
123```
124
125The result for the programming is that you can use the `timestamp` at `module` template:
126
127```html
128Timestamp: {{timestamp}}
129```