diff options
author | Marcel Amirault <mamirault@gitlab.com> | 2021-08-18 09:44:43 +0300 |
---|---|---|
committer | Marcel Amirault <mamirault@gitlab.com> | 2021-08-26 03:47:36 +0300 |
commit | c44eb95b447e50d5a2e17f086be911a3b9435bd9 (patch) | |
tree | bf0d5e0ecd55f789af2c8e0b242d15c576a15bb7 /doc/development.md | |
parent | c2c62c2a813c412d8d2dd8bf00bae140c789cd53 (diff) |
Move docs site readme content into docs
All our docs site documentation was in one large readme.
This moves everything into /doc and puts them into
specific pages for each topic.
Diffstat (limited to 'doc/development.md')
-rw-r--r-- | doc/development.md | 93 |
1 files changed, 93 insertions, 0 deletions
diff --git a/doc/development.md b/doc/development.md new file mode 100644 index 00000000..28327c85 --- /dev/null +++ b/doc/development.md @@ -0,0 +1,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). |