revise documentation for adding new fonts to the UI

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index ef86635..e549a14 100644 (file)
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -4,6 +4,7 @@
 * 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]

diff --git a/docs/modules/ROOT/pages/add-fonts.adoc b/docs/modules/ROOT/pages/add-fonts.adoc
new file mode 100644 (file)
index 0000000..19fc121
--- /dev/null
+++ b/docs/modules/ROOT/pages/add-fonts.adoc
@@ -0,0 +1,102 @@
+= 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 two steps involved:
+
+. Add the font to your UI project
+. Add a font-face declaration to your stylesheet
+
+You can then reference the font family 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).
+
+. Repeat the previous step 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;
+}
+----
+
+. 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.
+
+. Repeat the previous step 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;
+}
+----
+
+. 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.

diff --git a/docs/modules/ROOT/pages/changing-fonts.adoc b/docs/modules/ROOT/pages/changing-fonts.adoc
deleted file mode 100644 (file)
index edba5e3..0000000
--- a/docs/modules/ROOT/pages/changing-fonts.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-= Changing Fonts
-
-There are two easy ways to change fonts:
-
-== Use Yarn to Install a Font
-
-. Use npm or yarn to install your new font package
-. In `./antora-ui-default/src/css` add a new css file: `typeface-name-of-your-font.css`
-. Import your font:
-+
-```css
-@font-face {
-  font-family: "name of your font";
-  font-style: normal;
-  font-weight: 400;
-  src:
-    local("name of your font"),
-    url(~name-of-your-package/files/name-of-your-font.woff) format("woff"),
-}
-```
-. Do this for each style (ie bold, monospace, etc) that you want to use.
-. Change the css to actually use your newly imported font. For example, if you want to use your font for all normal text on the site, you can edit `base.css` where it specifies the `font-family`:
-+
-```css
-html {
-  box-sizing: border-box;
-  font-family: "name of your font", sans-serif;
-  font-size: 1.1em;
-  text-size-adjust: 100%;
-}
-```
-. Save everything and test out the new font with `gulp preview`
-
-
-== Manually add Font Files
-
-To manually add font files, add them to `./antora-ui-default/src/font`. Next, you need to import them in the site's css:
-
-. In `./antora-ui-default/src/css` add a new css file: `typeface-name-of-your-font.css`
-. Import your font:
-+
-```css
-@font-face {
-  font-family: "Name Of Your Font";
-  font-weight: 400;
-  src: url("../font/name-of-your-font.otf");
-}
-```
-. Do this for each style (ie bold, monospace, etc) that you want to use.
-. Change the css to actually use your newly imported font. For example, if you want to use your font for all normal text on the site, you can edit `base.css` where it specifies the `font-family`:
-+
-```css
-html {
-  box-sizing: border-box;
-  font-family: "name of your font", sans-serif;
-  font-size: 1.1em;
-  text-size-adjust: 100%;
-}
-```
-. Save everything and test out the new font with `gulp preview`