Clean

.gitlab-ci.yml

@@ -0,0 +1,55 @@
+image: node:10.14.2-stretch
+stages: [setup, verify, deploy]
+install:
+  stage: setup
+  cache:
+    paths:
+    - .cache/npm
+  script:
+  - &npm_install
+    npm install --quiet --no-progress --cache=.cache/npm
+lint:
+  stage: verify
+  cache: &pull_cache
+    policy: pull
+    paths:
+    - .cache/npm
+  script:
+  - *npm_install
+  - node_modules/.bin/gulp lint
+bundle-stable:
+  stage: deploy
+  only:
+  - master@antora/antora-ui-default
+  cache: *pull_cache
+  script:
+  - *npm_install
+  - node_modules/.bin/gulp bundle
+  artifacts:
+    paths:
+    - build/ui-bundle.zip
+bundle-dev:
+  stage: deploy
+  except:
+  - master
+  cache: *pull_cache
+  script:
+  - *npm_install
+  - node_modules/.bin/gulp bundle
+  artifacts:
+    expire_in: 1 day # unless marked as keep from job page
+    paths:
+    - build/ui-bundle.zip
+pages:
+  stage: deploy
+  only:
+  - master@antora/antora-ui-default
+  cache: *pull_cache
+  script:
+  - *npm_install
+  - node_modules/.bin/gulp preview:build
+  # FIXME figure out a way to avoid copying these files to preview site
+  - rm -rf public/_/{helpers,layouts,partials}
+  artifacts:
+    paths:
+    - public

.stylelintrc

@@ -3,5 +3,11 @@
   "rules": {
     "comment-empty-line-before": null,
     "no-descending-specificity": null,
+    "at-rule-no-unknown": [
+      true,
+      {
+        "ignoreAtRules": ["tailwind", "responsive"]
+      }
+    ]
   }
 }

docs/antora.yml

@@ -0,0 +1,5 @@
+name: antora-ui-default
+title: Antora Default UI
+version: master
+nav:
+- modules/ROOT/nav.adoc

docs/modules/ROOT/nav.adoc

@@ -0,0 +1,13 @@
+* xref:prerequisites.adoc[UI Development Prerequisites]
+* xref:set-up-project.adoc[Set up a UI Project]
+* xref:build-preview-ui.adoc[Build and Preview the UI]
+* xref:development-workflow.adoc[UI Development Workflow]
+* xref:templates.adoc[Work with the Handlebars Templates]
+* xref:stylesheets.adoc[Work with the CSS Stylesheets]
+ ** xref:add-fonts.adoc[Add Fonts]
+* xref:style-guide.adoc[UI Element Styles]
+** xref:inline-text-styles.adoc[Inline Text]
+** xref:admonition-styles.adoc[Admonitions]
+** xref:list-styles.adoc[Lists]
+** xref:sidebar-styles.adoc[Sidebars]
+** xref:ui-macro-styles.adoc[UI Macros]

docs/modules/ROOT/pages/add-fonts.adoc

@@ -0,0 +1,123 @@
+= Add Fonts
+
+This page explains how to add new fonts to your UI.
+These instructions assume you've forked the default UI and are able to customize it.
+
+There are three steps involved:
+
+. Add the font to your UI project
+. Add a font-face declaration to your stylesheet
+. Use the new font in your stylesheet
+
+How you reference the font file in the font-face declaration depends on how you decide to manage it.
+You can manage the font with npm or download it manually and add it directly to your UI project.
+The following sections describe each approach in turn.
+
+== npm managed
+
+You can use npm (or Yarn) to manage the font.
+This approach saves you from having to store the font file directly in your UI project.
+Here are the steps involved.
+
+. Use npm (or Yarn) to install the font files from a package (e.g., https://www.npmjs.com/package/typeface-open-sans[typeface-open-sans])
+
+ $ npm install --save typeface-open-sans
+
+. In [.path]_src/css_, add a corresponding CSS file (e.g., [.path]_typeface-open-sans.css_)
+. In that file, declare the font face:
++
+[source,css]
+----
+@font-face {
+  font-family: "Open Sans";
+  font-style: normal;
+  font-weight: 400;
+  src:
+    local("Open Sans"),
+    local("Open Sans-Regular"),
+    url(~typeface-open-sans/files/open-sans-latin-400.woff) format("woff")
+}
+----
++
+The Gulp build recognizes the `~` URL prefix and copies the font from the npm package to the build folder (and hence bundle).
++
+You must define one @font-face for each font weight and style combination (e.g., `font-weight: 500` + `font-style: italic`) from the font that you want to use in your stylesheet.
+
+. Import the typeface CSS file you just created into the main stylesheet, [.path]_src/css/site.css_ (adjacent to the other typeface imports):
++
+[source,css]
+----
+@import "typeface-open-sans.css";
+----
+
+. Repeat the previous steps for each font style and weight you want to use from that package.
+. Change the CSS to use your newly imported font:
++
+[source,css]
+----
+html {
+  font-family: "Open Sans", sans;
+}
+----
++
+TIP: If you're building on the default UI, you may instead want to define or update the font family using a variable defined in [.path]_src/css/vars.css_.
+
+. Test the new font by previewing your UI:
+
+ $ gulp preview
+
+If you see the new font, you've now successfully added it to your UI.
+If you aren't sure, look for the https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Edit_fonts[All fonts on page] section in your browser's developer tools to see whether the font was loaded.
+
+== Manual
+
+A simpler approach to adding fonts is to store them directly in your project.
+Here are the steps involved.
+
+. Download the font files and add them to the [.path]_src/font_ folder.
+Create this folder if it does not exist.
+. In [.path]_src/css_, add a corresponding CSS file (e.g., [.path]_typeface-open-sans.css_)
+. In that file, declare the font face:
++
+[source,css]
+----
+@font-face {
+  font-family: "Open Sans";
+  font-style: normal;
+  font-weight: 400;
+  src:
+    local("Open Sans"),
+    local("Open Sans-Regular"),
+    url(../font/open-sans-latin-400.woff) format("woff")
+}
+----
++
+Note that the path is a relative path starting from the [.path]_src/css_ folder to the [.path]_src/font_ folder.
++
+You must define one @font-face for each font weight and style combination (e.g., `font-weight: 500` + `font-style: italic`) from the font that you want to use in your stylesheet.
+
+. Import the typeface CSS file you just created into the main stylesheet, [.path]_src/css/site.css_ (adjacent to the other typeface imports):
++
+[source,css]
+----
+@import "typeface-open-sans.css";
+----
+
+. Repeat the previous steps for each font style and weight you want to use.
+. Change the CSS to use your newly imported font:
++
+[source,css]
+----
+html {
+  font-family: "Open Sans", sans;
+}
+----
++
+TIP: If you're building on the default UI, you may instead want to define or update the font family using a variable defined in [.path]_src/css/vars.css_.
+
+. Test the new font by previewing your UI:
+
+ $ gulp preview
+
+If you see the new font, you've now successfully added it to your UI.
+If you aren't sure, look for the https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Edit_fonts[All fonts on page] section in your browser's developer tools to see whether the font was loaded.

docs/modules/ROOT/pages/admonition-styles.adoc

@@ -0,0 +1,38 @@
+= Admonition Styles
+
+An xref:antora:asciidoc:admonitions.adoc[admonition], also known as a notice, helps draw attention to content with a special label or icon.
+
+== Admonition blocks
+
+An admonition block is a table.
+The table title element is specified by the block class: tip, note, important, warning, or caution.
+Here's an AsciiDoc source example that produces an admonition with the table title warning:
+
+[source,asciidoc]
+----
+WARNING: Watch out!
+----
+
+If font-based icons are enabled (`icons=font`), the table title text is replaced by the associated icon.
+
+[source,html]
+----
+<div class="admonitionblock warning">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-warning" title="Warning"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Watch out!</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+----
+
+Here's how it might appear when the title is displayed as text:
+
+WARNING: Watch out!

docs/modules/ROOT/pages/build-preview-ui.adoc

@@ -0,0 +1,70 @@
+= Build a UI Project for Local Preview
+// Settings:
+:idprefix:
+:idseparator: -
+:experimental:
+
+== Build Preview Site
+
+Once you've modified the site UI, the first thing you'll want to do is check out how it looks.
+That's what the files in the [.path]_preview-src/_ folder are for.
+This folder contains HTML file fragments that provide a representative sample of content from the site.
+The preview saves you from having to generate the whole site just to test the UI.
+These files should give you an idea of how the UI will look when applied to the actual site.
+
+The pages in the preview site are assembled using the Handlebars templates and link to the pre-compiled asset files (emulating the behavior of the site generator).
+Thus, to look at them, you need to run them through the UI build.
+
+There are two preview modes available.
+You can run the build once and examine the result or you can run the build continuously so you can see changes as you make them.
+The next two sections explain how to use these modes.
+
+=== Build Once
+
+To build the UI once for preview, then stop, execute the following command:
+
+ $ gulp preview:build
+
+This task pre-compiles the UI files into the [.path]_public_ directory.
+To view the preview pages, navigate to the HTML pages in the [.path]_public_ directory using your browser (e.g., [.path]_public/index.html_).
+
+=== Build Continuously
+
+To avoid the need to run the `preview:build` task over and over while developing, you can use the `preview` command instead to have it run continuously.
+This task also launches a local HTTP server so updates get synchronized with the browser (i.e., "`live reload`").
+
+To launch the preview server, execute the following command:
+
+ $ gulp preview
+
+You'll see a URL listed in the output of this command:
+
+....
+[12:59:28] Starting 'preview:serve'...
+[12:59:28] Starting server...
+[12:59:28] Server started http://localhost:5252
+[12:59:28] Running server
+....
+
+Navigate to the URL to view the preview site.
+While this command is running, any changes you make to the source files will be instantly reflected in the browser.
+This works by monitoring the project for changes, running the `preview:build` task if a change is detected, and sending the updates to the browser.
+
+Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
+
+== Package for Previewing
+
+If you need to bundle the UI in order to preview the UI on the real site in local development, run the following command:
+
+ $ gulp bundle
+
+The `bundle` command also invokes the `lint` command to check that the CSS and JavaScript follow the coding standards.
+
+The UI bundle will be available at [.path]_build/ui-bundle.zip_.
+You can then point Antora at this bundle using the `--ui-bundle-url` command-line option.
+
+If you have the preview running, and you want to bundle without causing the preview to be clobbered, use:
+
+ $ gulp bundle:pack
+
+The UI bundle will again be available at [.path]_build/ui-bundle.zip_.

docs/modules/ROOT/pages/development-workflow.adoc

@@ -0,0 +1,34 @@
+= UI Development Workflow
+// Settings:
+:idprefix:
+:idseparator: -
+
+// This section provides information about some of the UI files you'll be modifying and how to prepare and submit those changes.
+
+All changes pushed to a UI project's master branch can trigger a new release (not described here).
+Therefore, you want to make your changes to a development branch and submit it as a pull request (PR) to be approved.
+(Even better would be to issue the PR from a fork).
+Only when the PR is approved and merged will the new release be triggered.
+
+== git steps
+
+Use the following command to create a local development branch named `name-me`:
+
+ $ git checkout -b name-me -t origin/master
+
+You'll then apply your changes to the UI files.
+Once you're done making changes, commit those changes to the local branch:
+
+ $ git commit -a -m "describe your change"
+
+Then, push your branch to the remote repository:
+
+ $ git push origin name-me
+
+Finally, navigate to your UI project in your browser and create a new pull request from this branch.
+
+The maintainer of the UI should review the changes.
+If the changes are acceptable, the maintainer will merge the pull request.
+As soon as the pull request is merged into master, an automated process will take over to publish a new release for the site generator to use.
+
+Now that you've got the process down, let's review some of the files you'll be working with in more detail.