From: Dan Allen Date: Sun, 16 Jun 2019 00:51:30 +0000 (-0600) Subject: revise documentation for adding new fonts to the UI X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=bbda455049d73c1b4ee3084cdb3bf79463db5a7b;p=working%2Feg-antora.git 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 --- 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 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 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`