Merge pull request #11613 from thaJeztah/faster_builds

Optimize configuration and layout to reduce build-time

Dockerfile

@@ -57,14 +57,14 @@ COPY --from=upstream-resources /usr/src/app/md_source/. ./
 RUN ./_scripts/update-api-toc.sh
 ARG JEKYLL_ENV
 RUN echo "Building docs for ${JEKYLL_ENV} environment"
-RUN set -eux; \
+RUN set -eu; \
  if [ "${JEKYLL_ENV}" = "production" ]; then \
-    jekyll build -d ${TARGET} --config _config.yml,_config_production.yml; \
+    jekyll build --profile -d ${TARGET} --config _config.yml,_config_production.yml; \
+    sed -i 's#<loc>/#<loc>https://docs.docker.com/#' "${TARGET}/sitemap.xml"; \
  else \
-    jekyll build -d ${TARGET}; \
+    jekyll build --profile -d ${TARGET}; \
  fi; \
- find ${TARGET} -type f -name '*.html' | while read i; do sed -i 's#\(<a[^>]* href="\)https://docs.docker.com/#\1/#g' "$i"; done; \
+ find ${TARGET} -type f -name '*.html' | while read i; do sed -i 's#\(<a[^>]* href="\)https://docs.docker.com/#\1/#g' "$i"; done;
- sed -i 's#<loc>/#<loc>https://docs.docker.com/#' "${TARGET}/sitemap.xml";
 
 
 # This stage only contains the generated files. It can be used to host the

_config.yml

@@ -1,3 +1,8 @@
+##
+# Default configuration file
+#
+# This file overrides options set in _config.yml for production / deploy
+##
 name: Docker Documentation
 markdown: kramdown
 kramdown:
@@ -11,11 +16,10 @@ incremental: true
 permalink: pretty
 safe: false
 lsi: false
-exclude: ["_samples", "_scripts", "404.html", "datacenter", "ee", "index.html"]
+exclude: ["_samples", "_scripts", "404.html", "datacenter", "ee", "index.html", "js/metadata.json"]
 
 # Component versions -- address like site.docker_ce_version
 # You can't have - characters in these for non-YAML reasons
-
 latest_engine_api_version: "1.40"
 docker_ce_version: "19.03"
 compose_version: "1.27.4"
@@ -24,15 +28,34 @@ compose_file_v2: "2.4"
 machine_version: "0.16.0"
 distribution_version: "2.7"
 
-collections:
+# List of plugins to enable for local development builds. Mostly the same as
-  samples:
+# for production, but without the "jekyll-sitemap" plugin, which is not needed
-    output: true
+# for previewing, and excluding saves some time to build
-
 plugins:
   - jekyll-redirect-from
   - jekyll-relative-links
-  - jekyll-sitemap
 
+# Assets
+#
+# We specify the directory for Jekyll so we can use @imports.
+#
+# For local development, we build css with the "expanded" format to produce
+# human-readable output for easier debugging.
+sass:
+  sass_dir: _scss
+  style: expanded
+
+# Set default options / metadata for some paths.
+#
+# Setting options here prevents having to repeat the same option in front-matter
+# on every page. Avoid using wildcards, such as "path: engine/api/v1.*", as
+# limitations in Jekyll cause those to introduce a _severe_ impact on build-time,
+# affecting generation of (e.g.) sitemap.xml and metadata.json, resulting in the
+# total build to take 60 seconds longer to build (!).
+#
+# The list below is for "development" (local builds, and PR previews) builds only,
+# and should be kept minimal to allow for fast builds. Other options should go
+# into _config_production.yml, which is used for production deploys.
 defaults:
   - scope:
       path: ""
@@ -42,78 +65,7 @@ defaults:
       toc_min: 2
       toc_max: 3
 
-  # Set the correct edit-URL for upstream resources. We usually don't create a direct
-  # edit link for these, and instead point to the directory that contains the file.
-  - scope:
-      path: engine/api/v1.*
-    values:
-      edit_url: "https://github.com/docker/docker/tree/master/docs/api"
-  - scope:
-      path: engine/deprecated
-    values:
-      edit_url: "https://github.com/docker/cli/tree/master/docs/"
-  - scope:
-      path: engine/extend
-    values:
-      edit_url: "https://github.com/docker/cli/tree/master/docs/extend"
-  - scope:
-      path: engine/reference
-    values:
-      edit_url: "https://github.com/docker/cli/tree/master/docs/reference"
   - scope:
       path: engine/reference/commandline
     values:
-      edit_url: "https://github.com/docker/cli/tree/master/docs/reference/commandline"
       skip_read_time: true
-  - scope:
-      path: glossary
-    values:
-      edit_url: "https://github.com/docker/docker.github.io/blob/master/_data/glossary.yaml"
-  - scope:
-      path: notary/reference
-    values:
-      edit_url: "https://github.com/theupdateframework/notary/tree/master/docs/reference"
-  - scope:
-      path: registry/configuration
-    values:
-      edit_url: "https://github.com/docker/distribution/tree/master/docs"
-  - scope:
-      path: registry/spec
-    values:
-      edit_url: "https://github.com/docker/distribution/tree/master/docs/spec"
-  - scope:
-      path: compliance
-    values:
-      edit_url: "https://github.com/mirantis/compliance/tree/master/docs/compliance"
-
-  # Hide Enterprise content from sitemap. These directories still contains stubs
-  # that are needed to redirect old URLs
-  - scope:
-      path: "datacenter"
-    values:
-      sitemap: false
-      title: Docker Enterprise moved to Mirantis
-  - scope:
-      path: "desktop/enterprise"
-    values:
-      sitemap: false
-  - scope:
-      path: "ee"
-    values:
-      sitemap: false
-      title: Docker Enterprise moved to Mirantis
-  - scope:
-      path: "machine"
-    values:
-      sitemap: false
-  - scope:
-      path: "samples/library"
-    values:
-      sitemap: false
-
-# Assets
-#
-# We specify the directory for Jekyll so we can use @imports.
-sass:
-  sass_dir: _scss
-  style: expanded

_config_production.yml

@@ -1,11 +1,112 @@
+##
+# This file overrides options set in _config.yml for production / deploy
+##
 
-# Include files that are excluded in "development" ("enterprise" stubs) for production
+# Override the exclusion list to include files that are excluded in "development",
+# such as the "enterprise" stubs, which are in place to facilitate redirects
+# to Mirantis.
 exclude: ["_scripts", "404.html", "index.html"]
 
 # Google Analytics, etc.
 google_analytics: GTM-WL2QLG5
 polldaddy_id:     8453675
 
+plugins:
+  - jekyll-redirect-from
+  - jekyll-relative-links
+  - jekyll-sitemap
+
 # Assets
+#
+# For production/deploy, we build css with the "compressed" format, to produce
+# smaller files.
 sass:
   style:    compressed
+
+collections:
+  samples:
+    output: true
+
+# Set default options / metadata for some paths.
+#
+# Setting options here prevents having to repeat the same option in front-matter
+# on every page. Avoid using wildcards, such as "path: engine/api/v1.*", as
+# limitations in Jekyll cause those to introduce a _severe_ impact on build-time,
+# affecting generation of (e.g.) sitemap.xml and metadata.json, resulting in the
+# total build to take 60 seconds longer to build (!).
+#
+# The list below is used for *production* deploys, and overrides the one defined
+# in "_config.yml", which is used for local builds and pull-request previews.
+defaults:
+  - scope:
+      path: ""
+      type: "pages"
+    values:
+      layout: docs
+      toc_min: 2
+      toc_max: 3
+
+  # Set the correct edit-URL for upstream resources. We usually don't create a direct
+  # edit link for these, and instead point to the directory that contains the file.
+  - scope:
+      path: engine/deprecated.md
+    values:
+      edit_url: "https://github.com/docker/cli/tree/master/docs/"
+  - scope:
+      path: engine/extend.md
+    values:
+      edit_url: "https://github.com/docker/cli/tree/master/docs/extend"
+  - scope:
+      path: engine/reference
+    values:
+      edit_url: "https://github.com/docker/cli/tree/master/docs/reference"
+  - scope:
+      path: engine/reference/commandline
+    values:
+      edit_url: "https://github.com/docker/cli/tree/master/docs/reference/commandline"
+      skip_read_time: true
+  - scope:
+      path: glossary.md
+    values:
+      edit_url: "https://github.com/docker/docker.github.io/blob/master/_data/glossary.yaml"
+  - scope:
+      path: notary/reference
+    values:
+      edit_url: "https://github.com/theupdateframework/notary/tree/master/docs/reference"
+  - scope:
+      path: registry/configuration
+    values:
+      edit_url: "https://github.com/docker/distribution/tree/master/docs"
+  - scope:
+      path: registry/spec
+    values:
+      edit_url: "https://github.com/docker/distribution/tree/master/docs/spec"
+  - scope:
+      path: compliance
+    values:
+      edit_url: "https://github.com/mirantis/compliance/tree/master/docs/compliance"
+
+  # Hide Enterprise content from sitemap. These directories still contains stubs
+  # that are needed to redirect old URLs
+  - scope:
+      path: "datacenter"
+    values:
+      sitemap: false
+      title: Docker Enterprise moved to Mirantis
+  - scope:
+      path: "desktop/enterprise"
+    values:
+      sitemap: false
+  - scope:
+      path: "ee"
+    values:
+      sitemap: false
+      title: Docker Enterprise moved to Mirantis
+  - scope:
+      path: "machine"
+    values:
+      sitemap: false
+  - scope:
+      path: "samples/library"
+    values:
+      sitemap: false

_includes/body.html

@@ -1,77 +0,0 @@
-{%- if page.edit_url -%}
-    {%- assign edit_url = page.edit_url -%}
-{%- else -%}
-    {%- assign edit_url = "https://github.com/docker/docker.github.io/edit/master/" | append: page.path -%}
-{%- endif -%}
-<body class="colums">
-    <header>
-        {% include header.html %}
-    </header>
-    <div class="wrapper right-open">
-        <div class="container-fluid">
-            <div class="row">
-                <div class="col-body">
-                    <main class="col-content content">
-                        <section class="section">
-                            {%- if page.title -%}
-                            <h1>{{ page.title }}</h1>
-                            {%- endif -%}
-                            {%- if page.advisory -%}
-                            <blockquote>{{ site.data.advisories.texts[page.advisory] | markdownify }}</blockquote>
-                            {%- endif -%}
-                            {%- unless page.skip_read_time == true -%}{% include read_time.html %}{%- endunless -%}
-                            {{ content }}
-                            {%- unless page.notags == true -%}
-                            {%- assign keywords = page.keywords | split:"," -%}
-                            {%- if keywords.size > 0 -%}
-                            <span class="glyphicon glyphicon-tags" style="padding-right: 10px"></span><span style="vertical-align: 2px">
-                                {%- for keyword in keywords -%}
-                                {%- assign strippedKeyword = keyword | strip -%}
-                                <a href="/search/?q={{ strippedKeyword }}">{{ strippedKeyword }}</a>
-                                {%- unless forloop.last %}, {% endunless -%}
-                                {%- endfor -%}
-                            </span>
-                            {%- endif -%}
-                            {%- endunless %}
-                            {%- if site.polldaddy_id and page.noratings != true -%}
-                            <div class="ratings-div"><div id="pd_rating_holder_{{ site.polldaddy_id }}"></div></div>
-                            {%- endif -%}
-                        </section>
-                    </main>
-                    <nav class="col-nav">
-                        <div id="sidebar-nav" class="sidebar hidden-sm hidden-xs">
-                            {% include side-menu.html %}
-                        </div>
-                    </nav>
-                    <div class="col-toc">
-                        <div class="sidebar hidden-xs hidden-sm">
-                            <div class="toc-nav">
-                                <div class="feedback-links">
-                                    <ul>
-                                        {%- if edit_url != "" -%}
-                                        <li><a href="{{ edit_url }}"><i class="fa fa-pencil-square-o" aria-hidden="true"></i> Edit this page</a></li>
-                                        {%- endif -%}
-                                        <li><a href="https://github.com/docker/docker.github.io/issues/new?body=File: [{{ page.path }}](https://docs.docker.com{{ page.url }})" class="nomunge"><i class="fa fa-check" aria-hidden="true"></i> Request docs changes</a></li>
-                                        <li>{%- include theme-switch.html -%}</li>
-                                    </ul>
-                                </div>
-                                {%- unless page.notoc -%}
-                                {%- assign my_min = page.toc_min | default: site.toc_min | default: 2 -%}
-                                {%- assign my_max = page.toc_max | default: site.toc_max | default: 3 -%}
-                                {%- assign my_name = page.url | default: "unnamed" -%}
-                                <div id="side-toc-title">On this page:</div>
-                                {%- include toc_pure_liquid.html html=content sanitize=true class="inline_toc" id="my_toc" toc_min=my_min toc_max=my_max page_name=my_name -%}
-                                {%- endunless -%}
-                            </div>
-                        </div>
-                    </div>
-                </div>
-            </div>
-        </div>
-    </div>
-    <footer class="footer">
-        {% include footer.html %}
-    </footer>
-    <script>const pageURL = "{{ page.url }}";</script>
-    {%- if jekyll.environment == 'production' -%}{%- include analytics/polldaddy.html -%}{%- endif -%}
-</body>

_includes/side-menu.html

@@ -1,4 +0,0 @@
-<div id="navbar" class="nav-sidebar">
-    <ul class="nav jsTOCHorizontal hidden-md hidden-lg"></ul>
-    <ul class="nav" id="jsTOCLeftNav"></ul>
-</div>

_layouts/docs.html

@@ -1,10 +1,90 @@
-<!-- Page generated {{ site.time }} -->
+<!-- Page generated {{ site.time }}
+{%- if page.edit_url -%}
+    {%- assign edit_url = page.edit_url -%}
+{%- else -%}
+    {%- assign edit_url = "https://github.com/docker/docker.github.io/edit/master/" | append: page.path -%}
+{%- endif -%} -->
 <!DOCTYPE html>
 <html lang="en">
 {%- include head.html -%}
-{%- if page.landing == true -%}
+<body class="colums">
-    {%- include body-landing.html -%}
+    <header>
-{%- else -%}
+        {% include header.html %}
-    {%- include body.html -%}
+    </header>
+    <div class="wrapper right-open">
+        <div class="container-fluid">
+            <div class="row">
+                <div class="col-body">
+                    <main class="col-content content">
+                        <section class="section">
+                            {%- if page.title -%}
+                            <h1>{{ page.title }}</h1>
                             {%- endif -%}
+                            {%- if page.advisory -%}
+                            <blockquote>{{ site.data.advisories.texts[page.advisory] | markdownify }}</blockquote>
+                            {%- endif -%}
+                            {%- unless page.skip_read_time == true -%}
+                            {%- assign words = content | number_of_words -%}
+                            {%- if words >= 360 -%}
+                            <p><em class="reading-time">Estimated reading time: {{ words | divided_by:180 }} minutes</em></p>
+                            {%- endif -%}
+                            {%- endunless -%}
+                            {{ content }}
+                            {%- unless page.notags == true -%}
+                            {%- assign keywords = page.keywords | split:"," -%}
+                            {%- if keywords.size > 0 -%}
+                            <span class="glyphicon glyphicon-tags" style="padding-right: 10px"></span><span style="vertical-align: 2px">
+                                {%- for keyword in keywords -%}
+                                {%- assign strippedKeyword = keyword | strip -%}
+                                <a href="/search/?q={{ strippedKeyword }}">{{ strippedKeyword }}</a>
+                                {%- unless forloop.last %}, {% endunless -%}
+                                {%- endfor -%}
+                            </span>
+                            {%- endif -%}
+                            {%- endunless %}
+                            {%- if site.polldaddy_id and page.noratings != true -%}
+                            <div class="ratings-div"><div id="pd_rating_holder_{{ site.polldaddy_id }}"></div></div>
+                            {%- endif -%}
+                        </section>
+                    </main>
+                    <nav class="col-nav">
+                        <div id="sidebar-nav" class="sidebar hidden-sm hidden-xs">
+                            <div id="navbar" class="nav-sidebar">
+                                <ul class="nav jsTOCHorizontal hidden-md hidden-lg"></ul>
+                                <ul class="nav" id="jsTOCLeftNav"></ul>
+                            </div>
+                        </div>
+                    </nav>
+                    <div class="col-toc">
+                        <div class="sidebar hidden-xs hidden-sm">
+                            <div class="toc-nav">
+                                <div class="feedback-links">
+                                    <ul>
+                                        {%- if edit_url != "" -%}
+                                        <li><a href="{{ edit_url }}"><i class="fa fa-pencil-square-o" aria-hidden="true"></i> Edit this page</a></li>
+                                        {%- endif -%}
+                                        <li><a href="https://github.com/docker/docker.github.io/issues/new?body=File: [{{ page.path }}](https://docs.docker.com{{ page.url }})" class="nomunge"><i class="fa fa-check" aria-hidden="true"></i> Request docs changes</a></li>
+                                        <li>{%- include theme-switch.html -%}</li>
+                                    </ul>
+                                </div>
+                                {%- unless page.notoc -%}
+                                {%- assign my_min = page.toc_min | default: site.toc_min | default: 2 -%}
+                                {%- assign my_max = page.toc_max | default: site.toc_max | default: 3 -%}
+                                {%- assign my_name = page.url | default: "unnamed" -%}
+                                <div id="side-toc-title">On this page:</div>
+                                {%- include toc_pure_liquid.html html=content sanitize=true class="inline_toc" id="my_toc" toc_min=my_min toc_max=my_max page_name=my_name -%}
+                                {%- endunless -%}
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+    <footer class="footer">
+        {% include footer.html %}
+    </footer>
+    <script>const pageURL = "{{ page.url }}";</script>
+    {%- if jekyll.environment == 'production' -%}{%- include analytics/polldaddy.html -%}{%- endif -%}
+</body>
 </html>

index.md

@@ -1,7 +1,7 @@
 ---
 description: Home page for Docker's documentation
 keywords: Docker, documentation, manual, guide, reference, api, samples
-landing: true
+layout: landing
 title: Docker Documentation
 notoc: true
 notags: true