Updated README to include documentation for usage, fixes #14

README.md

@@ -2,13 +2,56 @@
 
 Bifocal is is a minimal theme for [Ghost](https://github.com/TryGhost/Ghost) based on Solo. It features a two-column layout when screen width allows and displays internal tags to the visitor.
 
-Additional features include adaptive light/dark theme, a table of contents, a cat, and email obfuscation. Please note that the theme includes a robots.txt file that tells most web scrapers to ignore your site, although not all of them listen.
+Additional features include adaptive light/dark theme, a table of contents, and email obfuscation. Please note that the theme comes with a robots.txt file that tells most web scrapers to ignore your site, although not all of them listen.
 
 # Instructions
 
-1. Download this theme
+1. [Download this theme](https://git.viscogliosi-pate.com/jean/Bifocal/releases)
 2. Log into Ghost, and go to the `Design` settings area to upload the zip file
 
+# Usage
+
+## Feature images
+
+The maximum width that an image will be rendered at is 1200px. 1200px wide by 225px tall is the ideal height for feature images. Be aware that the featured image for a post is not used within that post.
+
+## Using internal tags
+
+Internal tags can be added from the Tags page in Ghost's admin interface. All internal tags are prefixed with a hash. Tag behavior in this theme is dependent on whether it has an associated image.
+
+### How to add text after a post's title
+
+Do not add an image to your internal tag. Only the **Description** field is used.
+
+### How to add icons above a post's title
+
+- The **Tag image** field is the icon file. This is assumed to be an SVG with an `id` matching the tag's **Meta description**. The SVG must be structured this way to support `fill=currentColor`, which enables the icon to be themed with the website.
+- The **Meta title** field is used for the image title and alt text.
+- The **Description** field is the text that accompanies the icon, if present.
+
+### How to hide publication date and/or table of contents
+
+1. Any post with an internal tag named `#hide date` will have the publication date hidden.
+2. Any post with an internal tag named `#hide toc` will have the table of contents hidden.
+
+## Theme settings
+
+### Accent color
+
+This option is only used for link color.
+
+### Email obfuscation
+
+This feature requires JavaScript to be enabled for site visitors, but will have no impact on their experience of using the website. Please enter your email [encrypted with ROT13](https://rot13.com/) in the **Email address** field of the `Site-wide` settings. This feature is implemented to prevent bot scraping of your email address and should prevent spam.
+
+### Socials
+
+Include the full URL to your profile instead of your handle alone. Empty socials will not be accessible to visitors.
+
+### Oneko
+
+This setting toggles the cat that chases the visitor's mouse. It's a very cute and fun addition! Text-heavy sites may want to disable this feature because it can disrupt reading.
+
 # Development
 
 Edition styles are compiled using Gulp/PostCSS to polyfill future CSS spec. You'll need [Node](https://nodejs.org/), [Yarn](https://yarnpkg.com/) and [Gulp](https://gulpjs.com) installed globally. As an alternative, install [Nix](https://nixos.org/) and type `nix develop` with the experimental flakes feature enabled. After that, from the theme's root directory:
@@ -23,7 +66,7 @@ yarn dev
 
 Now you can edit `/assets/css/` files, which will be compiled to `/assets/built/` automatically.
 
-The `zip` Gulp task packages the theme files into `dist/solo.zip`, which you can then upload to your site.
+The `zip` Gulp task packages the theme files into `dist/bifocal.zip`, which you can then upload to your site.
 
 ```bash
 yarn zip
@@ -31,15 +74,11 @@ yarn zip
 
 ## Credits
 
-Original [Solo](https://github.com/TryGhost/Solo) theme relased under the MIT license by Ghost Foundation.
+- Original [Solo](https://github.com/TryGhost/Solo) theme relased under the MIT license by Ghost Foundation.
-
+- Font is [Wanted Sans](https://github.com/wanteddev/wanted-sans), released under the SIL Open Font License 1.1 by Wanted Lab, Inc.
-Font is [Wanted Sans](https://github.com/wanteddev/wanted-sans), released under the SIL Open Font License 1.1 by Wanted Lab, Inc.
+- Email and RSS icons are from [Tabler Icons](https://github.com/tabler/tabler-icons), released under the MIT license by Paweł Kuna.
-
+- The cat that follows your cursor is [oneko.js](https://github.com/adryd325/oneko.js), released under the MIT license by adryd.
-Email and RSS icons are from [Tabler Icons](https://github.com/tabler/tabler-icons), released under the MIT license by Paweł Kuna.
+- The JavaScript for generating a table of contents is [Tocbot](https://github.com/tscanlin/tocbot), released under the MIT license by Tim Scanlin.
-
-The cat that follows your cursor is [oneko.js](https://github.com/adryd325/oneko.js), released under the MIT license by adryd.
-
-The JavaScript for generating a table of contents is [Tocbot](https://github.com/tscanlin/tocbot), released under the MIT license by Tim Scanlin.
 
 ## Copyright & License