blob: 28327c853c5dd870efe9776b1ae1cc7a2f0d9250 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
# GitLab docs site development
## Linking to source files
A helper called [`edit_on_gitlab`](/lib/helpers/edit_on_gitlab.rb) can be used
to link to a page's source file. We can link to both the simple editor and the
web IDE. Here's how you can use it in a Nanoc layout:
- Default editor:
`<a href="<%= edit_on_gitlab(@item, editor: :simple) %>">Simple editor</a>`
- Web IDE: `<a href="<%= edit_on_gitlab(@item, editor: :webide) %>">Web IDE</a>`
If you don't specify `editor:`, the simple one is used by default.
## Using YAML data files
The easiest way to achieve something similar to
[Jekyll's data files](https://jekyllrb.com/docs/datafiles/) in Nanoc is by
using the [`@items`](https://nanoc.ws/doc/reference/variables/#items-and-layouts)
variable.
The data file must be placed inside the `content/` directory and then it can
be referenced in an ERB template.
Suppose we have the `content/_data/versions.yaml` file with the content:
```yaml
versions:
- 10.6
- 10.5
- 10.4
```
We can then loop over the `versions` array with something like:
```erb
<% @items['/_data/versions.yaml'][:versions].each do | version | %>
<h3><%= version %></h3>
<% end &>
```
Note that the data file must have the `yaml` extension (not `yml`) and that
we reference the array with a symbol (`:versions`).
## Modern JavaScript
A lot of the JavaScript can be found in [`content/assets/javascripts/`](https://gitlab.com/gitlab-org/gitlab-docs/-/tree/main/content/assets/javascripts/content/assets/javascripts).
The files in this directory are handcrafted `ES5` JavaScript files.
We've [recently introduced](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/577)
the ability to write modern JavaScript. All modern JavaScript should be added to
the [content/frontend/](https://gitlab.com/gitlab-org/gitlab-docs/-/tree/main/content/frontend) directory.
### Add a new bundle
When adding a new bundle, the layout name (`html`) and bundle name (`js`) should
match to make it easier to find:
1. Add the new bundle to `content/frontend/<bundle-name>/<bundle-name>.js`.
1. Import the bundle in the HTML file `layouts/<bundle-name>.html`:
```html
<script src="<%= @items['/frontend/<bundle-name>/<bundle-name>.*'].path %>"></script>
```
You should replace `<bundle-name>` with whatever you'd like to call your
bundle.
## Bump versions of CSS and JavaScript
Whenever the custom CSS and JavaScript files under `content/assets/` change,
make sure to bump their version in the front matter. This method guarantees that
your changes take effect by clearing the cache of previous files.
Always use Nanoc's way of including those files, do not hardcode them in the
layouts. For example use:
```js
<script async type="application/javascript" src="<%= @items['/assets/javascripts/badges.*'].path %>"></script>
<link rel="stylesheet" href="<%= @items['/assets/stylesheets/toc.*'].path %>">
```
The links pointing to the files should be similar to:
```js
<%= @items['/path/to/assets/file.*'].path %>
```
Nanoc then builds and renders those links correctly according with what's
defined in [`Rules`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/Rules).
|
