Merge branch 'axil-skip-frontend' into 'main'

Add option to skip frontend compilation

Closes #1594

See merge request https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/3728

Merged-by: Sarah German <sgerman@gitlab.com>
Approved-by: Sarah German <sgerman@gitlab.com>
Co-authored-by: Achilleas Pipinellis <axil@gitlab.com>

3 files changed, 44 insertions, 0 deletions

diff --git a/Rules b/Rules
index af909d73..e6f927f6 100644
--- a/Rules
+++ b/Rules
@@ -183,6 +183,9 @@ layout '/**/*', :erb
 passthrough '/favicon.ico'
 
 postprocess do
+  # Skip the frontend compilation if NANOC_ENV=skip_frontend is set
+  # See doc/development.md
+  next if ENV['NANOC_ENV'] == 'skip_frontend'
   raise "Failed to copy GitLab fonts. Run 'yarn install' and try again." unless system('make add-gitlab-fonts')
   raise "postprocessing error" unless system('nanoc frontend')
 end
diff --git a/doc/development.md b/doc/development.md
index 8f39d026..105c32ad 100644
--- a/doc/development.md
+++ b/doc/development.md
@@ -246,3 +246,38 @@ To exclude a directory so the contents aren't published to the docs site:
 
 1. Edit [this `Rules` file](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/Rules).
 1. Add an `ignore` line, like: `ignore '/ee/drawers/*.md'`.
+
+## Skip compiling the frontend JavaScript
+
+When `nanoc compile` runs, all the JavaScript files under
+[`content/frontend/`](/content/frontend/) are compiled as well. This action is
+not idempotent, so the JavaScript files are built every time Nanoc compiles
+the site, regardless if a change has been made to one of those files. This means
+that even for a small Markdown file change like a typo, you have to wait almost
+two minutes for the frontend files to finish compiling so that you can preview
+your change locally.
+
+To avoid this, you can use the following workaround:
+
+1. Compile the frontend files once:
+
+   ```shell
+   make add-gitlab-fonts
+   bin/nanoc frontend
+   ```
+
+1. Use the `NANOC_ENV=skip_frontend` variable to skip compiling the frontend
+   files:
+
+   ```shell
+   NANOC_ENV=skip_frontend make live
+   ```
+
+This workaround uses Nanoc's [environments](https://nanoc.app/doc/sites/#environments)
+by setting one called
+[`skip_frontend`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/9544ee841dcde7591b21ec7f1400ddae495f0b8b/nanoc.yaml#L169)
+and defining the directories to skip
+[pruning](https://nanoc.app/doc/reference/config/#prune). We then use the
+name of the environment to set the `NANOC_ENV` variable and skip the
+[postprocess](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/ca31b96280072e5522ce42f4de89bd212fdf4ba2/Rules#L185)
+when compiling the frontend files.
diff --git a/nanoc.yaml b/nanoc.yaml
index 0c27e829..ebe682f1 100644
--- a/nanoc.yaml
+++ b/nanoc.yaml
@@ -164,3 +164,9 @@ checks:
       # Redirected link we don't want to update to platform/locale specific link
       # See https://gitlab.com/gitlab-org/gitlab/-/issues/368300#note_1047352091
       - 'https:\/\/support.gitlab.com'
+
+environments:
+  skip_frontend:
+    prune:
+      auto_prune: true
+      exclude: ['.git', 'frontend', 'assets']