@@ -53,52 +53,75 @@ Docsy includes the free FontAwesome icons by default, including logos for sites
5353like GitHub and Stack Overflow. You can view all available icons in the
5454[ FontAwesome documentation] ( https://fontawesome.com/icons/ ) , including the
5555FontAwesome version when the icon was added and whether it is available for free
56- tier users. Check Docsy's
57- [ ` package.json ` ] ( https://github.com/google/docsy/blob/main/package.json ) and
58- release notes for Docsy's currently included version of FontAwesome.
56+ tier users. Check Docsy's [ package.json] [ ] and release notes for Docsy's
57+ currently included version of FontAwesome.
5958
60- You can add FontAwesome icons to your
61- [ navbar] ( /docs/content/navigation/#adding-icons-to-the-navbar ) ,
62- [ side nav] ( /docs/content/navigation/#adding-icons-to-the-side-nav ) , or anywhere
63- in your text.
59+ You can add FontAwesome icons to your [ navbar] [ ] , [ side nav] [ ] , or anywhere in
60+ your text.
6461
6562## Add your favicons
6663
6764The theme ships no favicon files, but it ** discovers and links** a set of
68- conventionally named icons when you supply them: create your favicon files and
69- put them in your site project's ` static ` directory so they publish at the site
70- root (where browsers probe for them). The theme links whichever of these files
71- it finds, in this order, with no partial or configuration required:
72-
73- | File | Link |
74- | ---------------------- | -------------------------------------------------- |
75- | ` favicon.ico ` | ` rel="icon" ` with ` sizes="16x16 32x32 48x48" ` |
76- | ` favicon.svg ` | ` rel="icon" ` with ` type="image/svg+xml" ` |
77- | ` favicon-32x32.png ` | ` rel="icon" ` with ` type="image/png" sizes="32x32" ` |
78- | ` favicon-16x16.png ` | ` rel="icon" ` with ` type="image/png" sizes="16x16" ` |
79- | ` apple-touch-icon.png ` | ` rel="apple-touch-icon" ` |
65+ conventionally named icons when you supply them:
66+ [ create your favicon files] ( #generate-favicons ) and put them in your site
67+ project's ` static ` directory so they publish at the site root (where browsers
68+ probe for them). Docsy adds ` <link> ` elements inside each page's ` <head> ` for
69+ whichever of these files it finds, in this order:
70+
71+ | File | Link |
72+ | -------------------------- | ------------------------------------------------ |
73+ | ` favicon.ico ` | ` rel="icon" ` [ ^ ico-link ] |
74+ | ` favicon.svg ` | ` rel="icon" ` with ` type="image/svg+xml" ` |
75+ | ` favicon-NxN.png ` | ` rel="icon" ` with ` type="image/png" sizes="NxN" ` |
76+ | ` apple-touch-icon.png ` | ` rel="apple-touch-icon" ` (implicit size 180x180) |
77+ | ` apple-touch-icon-NxN.png ` | ` rel="apple-touch-icon" ` with ` sizes="NxN" ` |
78+
79+ If you have any square-size variants listed above, Docsy adds them in ascending
80+ size order.
81+
82+ [ ^ ico-link ] :
83+ The ` .ico ` link carries no ` sizes ` : the file is self-describing (browsers
84+ read the frame sizes it contains), so declaring sizes here would only risk
85+ drifting from the actual file. When you also supply a ` favicon.svg ` ,
86+ browsers that support SVG favicons (most modern ones) prefer it, and the
87+ ` .ico ` serves as the fallback.
8088
8189A modern ` favicon.ico ` plus an SVG and an ` apple-touch-icon.png ` covers common
82- browser and platform favicon needs. To customize the links -- for example to add
83- a web app manifest -- override the theme by adding your own
84- ` layouts/_partials/favicons.html ` partial; use ` relURL ` so links stay correct
85- when your site's ` baseURL ` includes a subpath.
90+ browser and platform favicon needs. For anything beyond that:
8691
87- You can generate favicons from a single image with an online tool such as
88- [ favicon.io] ( https://favicon.io ) or [ RealFaviconGenerator] [ rfg ] . If you have a
89- source SVG and [ ImageMagick] [ ] installed, Docsy also ships a helper script that
90- writes ` favicon.ico ` and ` apple-touch-icon.png ` for you:
92+ - Add web app manifest ` <link> ` elements to [ hooks/head-end.html] [ ] .
93+ - If you need to customize the favicon links themselves, override
94+ [ layouts/_ partials/favicons.html] [ ] . Make sure you use ` relURL ` so links stay
95+ correct when your site's ` baseURL ` includes a subpath.
96+
97+ ### Generate favicons
98+
99+ Don't have a favicon yet? You can generate favicons from a single image with an
100+ online tool such as [ favicon.io] ( https://favicon.io ) or
101+ [ RealFaviconGenerator] [ ] .
102+
103+ If you have a source SVG and [ ImageMagick] [ ] installed, Docsy also ships a
104+ ` gen-favicons ` helper. Save your source SVG as ` static/favicon.svg ` -- the theme
105+ links it directly -- then generate the raster icons alongside it. Run the
106+ command from your site project root.
107+
108+ For an npm package install of Docsy:
91109
92110``` sh
93- path/to/docsy/scripts/ gen-favicons.sh favicon.svg static/
111+ npx gen-favicons static/ favicon.svg static/
94112```
95113
96- The script writes only the raster icons (` favicon.ico ` and
97- ` apple-touch-icon.png ` ). If you also want an SVG favicon, copy your source SVG
98- to ` static/favicon.svg ` yourself -- the partial links it directly.
114+ Otherwise, run:
99115
100- [ ImageMagick ] : https://imagemagick.org
101- [ rfg ] : https://realfavicongenerator.net
116+ ``` sh
117+ node DOCSY_DIR/scripts/gen-favicons/cli.mjs static/favicon.svg static/
118+ ```
119+
120+ For a Git submodule install of Docsy, ` DOCSY_DIR ` is ` themes/docsy ` . For a Hugo
121+ module install of Docsy, ` DOCSY_DIR ` is the directory of your Docsy install,
122+ which you can find with ` go list -m -f '{{.Dir}}' github.com/google/docsy ` .
123+
124+ For the sizes and other options you can pass, run the command with ` --help ` .
102125
103126## Add images
104127
@@ -113,15 +136,11 @@ For example, the example site's landing page `content/en/_index.md` uses the
113136image ` content/en/featured-background.jpg ` , which is in the same directory --
114137see the [ content/en] [ ] folder on GitHub.
115138
116- [ content/en ] : https://github.com/google/docsy-example/tree/main/content/en
117-
118139Use the block's [ ` height ` parameter] [ ] to set the preferred display height of
119140the cover container (and therefore its image). For a full viewport height, use
120141` full ` , along with the ` td-below-navbar ` helper class to position the cover
121142below the navbar:
122143
123- [ `height` parameter ] : shortcodes/#blocks
124-
125144``` go-html-template
126145{{%/* blocks/cover
127146 title="Welcome to Docsy!"
@@ -145,8 +164,6 @@ For a shorter image, as in the [example site's About][] page, use one of `min`,
145164{{%/* /blocks/cover */%}}
146165```
147166
148- [ example site's About ] : < {{% param example_site_url %}}/about/ >
149-
150167### Other pages
151168
152169To add inline images to other pages, use the
@@ -155,3 +172,16 @@ prefer, just use regular Markdown or HTML images and add your image files to
155172your project's ` static ` directory. You can find out more about using this
156173directory in
157174[ Adding static content] ( /docs/content/adding-content/#adding-static-content ) .
175+
176+ <!-- prettier-ignore-start -->
177+ [ content/en ] : https://github.com/google/docsy-example/tree/main/content/en
178+ [ example site's About ] : < {{% param example_site_url %}}/about/ >
179+ [ `height` parameter ] : shortcodes/#blocks
180+ [ hooks/head-end.html ] : https://github.com/google/docsy/blob/main/theme/layouts/_partials/hooks/head-end.html
181+ [ ImageMagick ] : https://imagemagick.org
182+ [ layouts/_partials/favicons.html ] : https://github.com/google/docsy/blob/main/theme/layouts/_partials/favicons.html
183+ [ navbar ] : /docs/content/navigation/#adding-icons-to-the-navbar
184+ [ package.json ] : https://github.com/google/docsy/blob/main/package.json
185+ [ RealFaviconGenerator ] : https://realfavicongenerator.net
186+ [ side nav ] : /docs/content/navigation/#adding-icons-to-the-side-nav
187+ <!-- prettier-ignore-end -->
0 commit comments