thegetty / quire-docs

Documentation for Quire, a multiformat publishing framework

Quire

This is the reposistory for the Quire website and documentaiton.

About Quire

Developed by Getty, Quire is a digital publishing tool that can create dynamic publications in a variety of formats, including web, print, and e-book. Quire is an ideal tool for publishing beautiful, scholarly digital books optimized for visual imagery and designed to ensure publication content is widely accessible and stable.

Quire is open source and free to use. View Quire's 3-clause BSD open source license.

Please note: Quire v1 is currently in a pre-release phase. Testing and improvements are ongoing.

There are three Quire repositories hosted on GitHub:

• quire: Quire’s primary repository, with the command-line interface and 11ty template packages
• quire-starter-default: The default starter content for a Quire project
• quire-docs: Quire website and documentation.

Please see the README.md in our main repository wwww.github.com/thegetty/quire to learn more about the technical aspects of Quire, participate in the forum, submit bugs, and more.

Quire-Docs Repository

You are currently in the quire-docs repository. If you are new to Quire, contributing to this repository is an excellent way to get hands-on experience with the tool because the website and docs were actually built using Quire! We try to keep our site updated continuously for clarity and completeness, but it’s not always easy to keep up with the pace of Quire’s development. We invite you to read our Contributing Guidelines and learn how you can help us develop and refine these resources for the community.

There are four main sections to the website:

• About: Learn about what Quire can do, its history, and the team behind the project.
• Community: Connect with other users, see what others are creating with Quire, learn how to get involved.
• Documentation: Find instructions for how to use Quire from installation to deployment and everything in between. (Currently we have two sets of documentation v1 and v0. The latter is for the legacy version of Quire which will be phased out.)
• Resources: Get started by taking the Quire tutorial and peruse other helpful tools and resources to increase your Quire skillset.

Development Notes

This project was last built with the following software versions:

• Quire 0.20.1
• Node 14.18.1 / npm 6.14.15
• Hugo 0.72
• PrinceXML 14.2
• Pandoc 2.18

While v0.20.1 of the core Quire default theme was used, a number of customizations were made, including:

• Custom cover/homepage layout
• Use of Getty brand fonts
• Shortcodes for glossary definitions and the community showcase display
• Top navigation with section links and a static, always-open sidebar menu on most pages

Within the theme itself, changes were made to the source/css/variables.scss file. Outside of the theme, customizations can be found in the project’s layouts directory and in static/css/custom.css.

License

© 2022 J. Paul Getty Trust

The text and images of Quire’s documentation is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.

quire-docs's Issues

Add guide on linking

Users need to know how to create links to external resources, and to internal pages and to anchors within internal pages. This should include information about how element IDs are generated by Hugo and the Quire themes (particularly for figures, footnotes, bibliographic references, and headings) so that users can use those IDs as anchor links when they need to.

Add class handling to remove elements from EPUB or other outputs

Users or developers who add special features or interactivity into their Quire project, need a consistent way to hide/remove those things when outputting to other formats that don't have the necessary support for them, or when they simply don't want them included. In EPUB especially where many things can make the EPUB invalid, and the only other way to remove them would be to do so manually after outputting the file, or within the CLI itself.

I'd think maybe a series of classes .no-epub, .no-pdf that can be used together for different output types (known and unknown), with one umbrella class that captures them all, .no-output. The other option would be a data attribute, like data-epub="no". However, Quire currently supports a {{< q-class >}} shortcode which enables users to wrap markdown text in special class names. So using this shortcode in conjunction with one of the no-output classes would allow users to more easily control these options even at the markdown level, not just in the themes.

{{< q-class "no-output" >}}
    Text and other content that will display online only.
{{< /q-class >}}

Add object.yml and Object content model

For collection catalogues, Quire publications need to be able to handle Objects. Currently adding an object item with a number of arbitrary sub-attributes to the page YAML of a type: entry page will generate a table in the layout displaying that information.

title: The Luncheon on the Grass
weight: 101
object:
  artist: Édouard Manet
  year: 1863
  medium: Oil on canvas
  dimensions: 208 cm × 264.5 cm (81.9 in × 104.1 in)
  location: Musée d’Orsay, Paris
image: manet.jpg
type: entry

Along with this behavior, users should also be able to reference objects listed in an objects.yml file in the data directory by an id, rather than having the object data embedded directly in the page.

As mentioned above, the items listed under object are currently totally arbitrary. Whatever is listed there is automatically included in the generated table and there's nothing to say that the attributes will be consistent from project to project, or even from page to page. However, in its content model, Quire must define some attributes as specific, such as id so that we can meaningfully make use of them in templates. The obvious candidates might be those that are more regularized and data driven, such as start_date and end_date, or height and width. These in particular would let us implement sorting by dates, or showing a diagram of relative dimensions, both of which have been popular features in past catalogues. Are there other attributes like these that we should define as specific to an Object in Quire?

• Can/should Objects have Figures?
• Do we integrate Getty vocabs in some way to allow for more cross-linking? Meaning, can an Object have a Subject?
• In the case above, the object doesn't actually have a title of its own, the Page does. This is odd, but is it avoidable if every page has to have a title? Otherwise we're duplicating the title in two different places, which goes against our best practices.

Quire PC Installation Failure

I've been testing the install of the Quire CLI on a PC, and have run into a number of issues significant enough to make PC installation currently non-functional. I'm documenting the issues here, but until they can be resolved, PC users will have to be given a separate set of instructions to use only Hugo to work on Quire projects, and not have then have the ability to generate the PDF or EPUB formats that Quire makes possible.

Issues

1. mmmagic and node-gyp add significant install time and weight

Running pe-epub for EPUB generation requires also using pe-epub-fs for file handling. One of the dependencies for pe-epub-fs is mmmagic, which it turns out is installed through a native build process powered by node-gyp. From the mmmagic package.json file:

  "scripts": {
    "install": "node-gyp rebuild",
    "test": "node test/test.js"
  }

According to the documentation for node-gyp, a Visual C++ Build Environment and Python are required to run it. I installed these through a windows-build-tools script that worked well enough, but took an incredibly long time to complete.

npm install --global --production windows-build-tools

Once these were installed, node-gyp was functional and mmmagic was rebuilt during the npm install -g process on Quire CLI, though it added a significant installation time load there as well.

This doesn't seem to be a problem on a Mac, perhaps because Xcode has already been installed for git access and Python is pre-installed. Though even then it still might be causing performance delays that just aren't as specific.

2. Hugo is installed but PATH is not updated

The hugo-bin package is successfully installing the Hugo executable. However, one of the steps in a typical Windows Hugo install is to edit the Windows PATH settings to point the hugo command to the executable file. Assuming the quire-cli is installed in the main user directory, the PATH to be added would be:

C:\Users\[USER-DIRECTORY-NAME]\quire-cli\node_modules\hugo-bin\vendor

The Quire CLI depends on access to the hugo command, and so without the PATH edit, hugo and therefore quire commands won't work. That said, with Hugo now existing within quire-cli rather than as a separate install, perhaps it can be activated without the command itself, but rather more directly?

Note that I did not also test to see if the right Hugo version (32 or 64 bit) was installed based on my test PC's operation system. But this should be checked.

3. Theme dependencies don't automatically install

On either quire new or quire install the node dependencies in quire-starter-theme are not being installed automatically as they should, but instead need to be done manually.

cd themes/quire-starter-theme
npm install

4. PrinceXML works differently on a PC

Whereas on a Mac, PrinceXML can be called from the command line with the prince command, on Windows the default behavior is to call the program with the entire path, such as:

'/c/Program Files (x86)/Prince/engine/bin/prince.exe' --version

Rather than

prince --version

Because the Quire CLI is dependent on specific access to the prince command, quire pdf will not work on a PC. I did try following the PATH approach Hugo takes by editing the PATH to also point to Prince, but that didn't work for me.

Consider need for special pdf-only classes for figures

In Artistry in Bronze, we used a pdf shortcode attribute to adjust/override the way images were handled in the pdf/print edition and had handling for five different options: two-column, one-column, half-column-right, half-column-left, and no-grid. This gave flexibility but too much so. The issue is probably also most prevalent in two-column print layouts, whereas one-column layouts would reflect the online design in a more pleasant way. Regardless, it would be better to limit the number of options, or move them into the exiting class attribute rather than adding a new pdf one, or eliminate them altogether, or some combination of these.

Perhaps a simple is-bigger-print modifier class that would either move an image to one-column if it was a smaller float, or to two-column if it were already by default one-column. And an is-smaller-print to move images the other way?

{{< q-figure id="3.1" class="is-pulled-right  is-bigger-print" >}}

{{< q-figure id="3.1" class="is-plate  is-smaller-print" >}}

Find our Alice in Wonderland and update quire-starter content

Digital publishing projects often use Alice in Wonderland as sample content for demos. Quire needs sample content as well, but ideally it should be something that shows off its capabilities. Particularly figure images, citations and bibliographies, and catalogue entries. Currently, in quire-starter, we're using a mishmash of Wikipedia content. It would nice to have something a little nicer, and maybe even a little charming.

I'm not sure we'll find a single publication that shows everything we need it to show, but maybe we'll get close and can fake it the rest of the way? Or maybe we'll put together a nicer version of what we have now from various sources? Our own mini publication on Cézanne, or Greek sculpture, or Van Gogh's Irises? The only critical part is that the text and images are either public domain, cc-licensed, or Getty-owned.

So, what's our Alice in Wonderland?

Some sources:

• Wikipedia
• Project Gutenberg
• Virtual Library

Javascript in Quire Projects

Hi @geealbers and Quire team! I hope things are going well.

I wanted to throw an idea your way regarding how to handle javascript in Quire projects. Apologies in advance if an issue thread is not the best forum for this kind of discussion.

Quire strives for a high level of accessibility and progressive enhancement in the publications it creates, goals which too many web projects feel free to disregard. But at the same time Quire is also designed to offer some pretty high-level features in JS (full-text client side search, various multi-media components like maps, videos/etc, and an elegant UI).

In the JS world, there is often a tension between tools like React or Vue (which let developers write well-structured, easy-to-read code but force an all-or-nothing approach on the users), or older tools like jQuery or plain DOM scripting (which are more amenable to progressive enhancement but can make code organization much more difficult once things go beyond a basic level of complexity).

I recently came across Stimulus.js in my own work, and I think that it could be very useful in this project. It is developed by the same people behind Ruby on Rails, and embraces progressive enhancement as a philosophy. It is explicitly not a single-page-app framework. There is also a well-written guide.

Stimulus is a JavaScript framework with modest ambitions. Unlike other frameworks, Stimulus doesn’t take over your application’s entire front-end. Rather, it’s designed to augment your HTML by connecting elements to JavaScript objects automatically.

Using Stimulus would be a departure from the way we have organized JS in Quire projects in the past, but I think it would enable us to greatly simplify the JS we ship to users in the starter kit. It could even be used without a build system if you want to move away from doing so much with Webpack by default.

If this is something you want to consider, I could open a pull request in the starter-theme that shows how to use Stimulus for search functionality; that would probably be enough of an example to extrapolate from elsewhere. Happy to discuss further if there is interest.

Bring Hugo up to current version

When installed through the CLI, Hugo is currently locked to version v0.31 in Quire. This is due mostly to the change in v0.32 that introduced "page bundles" to the Hugo content model, and that fundamentally changed the way Hugo handles index.md files. However, at this time Hugo is on v0.41, and we need to work to bring Quire up to support that most recent version. We should also then determine and document a process for updating Hugo support as new versions are released.

Add analytics

Should add standard Google Analytics support, either with a custom Quire partial, or using Hugo's built-in partial, which looks for a tracking code to be defined through the googleAnalytics attribute in config.yml. The only question is whether Hugo's built in version also tracks file downloads.

Might also be worth looking into the option of integrating some open source analytics as well, such as Matomo (formerly Piwik).

Quire preview command on Mac terminal generates error; preview fails

Have updated quire-cli (0.1.0.alpha.13), and we all get this error when running quire preview--at home on Mac running Sierra and at work running Yosemite. If you go to localhost:1313 after this you get an "unable to connect" error.

[MacBook:] ska% cd gail-oxford
[MacBook:/gail-oxford] ska% quire preview
Launching preview server
Navigate to http://localhost:1313 to see your changes.
Press Control+C or type "quire stop" to stop the preview.
events.js:183
throw er; // Unhandled 'error' event
^

Error: spawn node_modules/.bin/webpack ENOENT
at _errnoException (util.js:992:11)
at Process.ChildProcess._handle.onexit (internal/child_process.js:190:19)
at onErrorNT (internal/child_process.js:372:16)
at _combinedTickCallback (internal/process/next_tick.js:138:11)
at process._tickCallback (internal/process/next_tick.js:180:9)
at Function.Module.runMain (module.js:695:11)
at startup (bootstrap_node.js:191:16)
at bootstrap_node.js:612:3
[MacBook:~/gail-oxford] ska%

Update default output names, and add option to pass in file path for PDF output

In the Alpha 11 release of the CLI, we added support to pass in a custom file page for the EPUB output, and should have the same option for the PDF output.

$ quire epub ./path/to/book.epub

$ quire pdf ./path/to/book.pdf

The current default for both is static/downloads/output.epub and static/downloads/output.pdf. However, we also update the default filename to be more specific to the users' book. The CLI should first use .Site.Data.publication.short_title if available, or .Site.Data.publication.title truncated in the same way Hugo's truncate function works, if there's no short_title specified, and then URLize it to lowercase with dashes: my-book-title.pdf

Add MOBI output

.mobi is the e-book file format for Amazon. A MOBI file can be created directly from the content.opf file of an EPUB, using Amazon's free (but not open source) KindleGen command line tool. We need to find a solution for Quire. After an initial failed search for open source solutions, I'm asking around the community as well, and will post back here. Otherwise, the quickest/dirtiest implementation might be to treat KindleGen like we do PrinceXML and require that users download it on their own so that Quire can then use it, though adding to the install process is not ideal. Thoughts?

Add design guides to documentation

@swambold1 shared the below examples from the Clyfford Still Museum website manual. They viaually map out for users how certain elements are created, and also the names of elements, based on what the final output pages look like. Once our starter theme design is dialed in and finalized, creating something like these for our primary page templates and content types could be of great use to users.

Add embed option for audio

Presumably Soundcloud. The goal is that Quire should have basic audio and video support from the beginning. If for some reason Soundcloud doesn't make sense, could implement html5 audio instead.

Add Photoswipe or similar library for image viewing

In past publications, we've used Photoswipe to allow figure images to be opened in a lightbox modal at their full size. Photoswipe is nice because it has no dependencies, and also includes image-to-image navigation, the option to include the figure caption and credit, and zooming and full-screen controls. However, we're open to other solutions if one makes sense, though the functionality should largely stay the same.

Document dependencies

The dependencies in quire-cli and quire-starter-theme should be documented. Each should include the basic description of the dependency and then a specific statement as to why we're using it and what it does. I'm not sure if there's a best practice for this, but I imagine it could all just be in a table in a page of the docs. Thoughts?

Remove jQuery from Google Analytics snippet

Our current Google Analytics snippet included some needed custom code to capture the download of certain file types (PDF, EPUB, etc.). However, the bit of code is written with jQuery and it would be nice to rewrite in straight JavaScript to remove this dependency. Note that we do use jQuery later in the code (imported in application.js) however, the GA snippet should operate independently of this.

Google Analytics not registering on Next/Prev page load

The Journal18 team that published an article using Quire, reported that Google Analytics wasn't tracking properly. It picks up page loads when you visit a page of the site directly, but if not if you navigate to it from within the publication using the next/prev arrows. I'm guessing the issue has to do with smoothState? Or, per Google's preferred method, the GA snippet is currently the last element in head of the file rather that at the bottom of the body where we've had it for previous books, like Roman Mosaics. Perhaps the source of the issue is as simple as this new load order?

Combine q-deepzoom and q-map shortcodes into one

Rather than having two separate shortcodes these could be combined into a single q-figure-zoom. They would be an extension of the Figure model, which includes the following base attributes:

- id:
  src:
  alt:
  caption: 
  credit:
  label_text:

But then, like for audio and video, which add a few additional attributes:

  media_type:
  media_id:
  aspect_ratio:

The q-figure-zoom would include attributes specific to its needs, perhaps:

  lat:
  long:
  geojson:
  iiif:
  zoom_level:

In this way we keep the simplicity of the content model intact, and indeed it makes sense that maps and large images are conceptually no different than other kinds of figure illustrations (only technically so). This also simplifies providing static fallbacks of these zooming images for use in the pdf and ebooks. It would be handled in the same way fallbacks are handled for videos, where a figure item that's a video includes both a src for the fallback and a media_id to reference the video itself. Couple other thoughts:

• media_type could also be used by expanding the possible types to include zoom and map.
• lat and long might be x and y (or lat_x and long_y) so that IIIF images could be centered to specific points just as maps are. And I think this will help down the road as we could seamlessly provide users a way to link to specific points in either maps or deep zoom images.

Update EPUB templates and build settings in CLI

While we have basic EPUB output working, there are a few remaining items to work in (cover image handling and CSS), as well as some changes that need to be made after the recent update to the content model.

• Update cover image to pull the one defined in .Site.Data.publication.promo_image
• Update creators handling to account for new content model. Rather than look for primary_contributor, needs to look for contributor with a type: "primary-contributor"
• Look into adding contributors handling for contributors with a type: "secondary-contributor". EPUB uses Dublin Core and so can support "creators" (as the primary) and "contributors" as the secondary group.
• For both creators and contributors, the name constructor should look for full_name first, and if not present use first_name and last_name. Not sure what to do with the file_as value when full_name is used, leave it out?
• Update description.full to strip out new lines (\n), and any HTML tags. I ran into a problem with this in trying to validate another EPUB.
• Remove the templates/epub directory and its contents, as these are now being handled through pe-epub.js.
• Add handling to pull in an optional epub.css file, which would live in the source/css directory of the theme as epub.scss.

Is it possible to install Linux?

Mac and PC installation documents are written.

So can I install Linux (Like ubuntu)?

Thank you

Additions to About page

Github recommends this link as further reading to create good readme files: https://open-source-guide.18f.gov/making-readmes-readable/

From the questions they suggest to answer in the readme file, these would be the ones we'd need to address:

Who uses Quire?
What is Quire’s goal?
How can you (or your institution) benefit from using Quire?

Install on Windows: theme submodule installation fails

On Windows 10 (64-bit).

Following the PC installation instructions, I get the following error when cloning the starter kit repo in step 3:

Submodule 'themes/quire-starter-theme' (https://github.com/gettypubs/quire-starter-theme.git) registered for path 'themes/quire-starter-theme'
Cloning into 'C:/Hugo/sites/quire-starter/themes/quire-starter-theme'...
fatal: HttpRequestException encountered.
   An error occurred while sending the request.
bash: /dev/tty: No such device or address
error: failed to execute prompt script (exit code 1)
fatal: could not read Username for 'https://github.com': No error
fatal: clone of 'https://github.com/gettypubs/quire-starter-theme.git' into submodule path 'C:/Hugo/sites/quire-starter/themes/quire-starter-theme' failed
Failed to clone 'themes/quire-starter-theme'. Retry scheduled
Cloning into 'C:/Hugo/sites/quire-starter/themes/quire-starter-theme'...
fatal: HttpRequestException encountered.
   An error occurred while sending the request.
bash: /dev/tty: No such device or address
error: failed to execute prompt script (exit code 1)
fatal: could not read Username for 'https://github.com': No error
fatal: clone of 'https://github.com/gettypubs/quire-starter-theme.git' into submodule path 'C:/Hugo/sites/quire-starter/themes/quire-starter-theme' failed
Failed to clone 'themes/quire-starter-theme' a second time, aborting

This results in an empty themes directory in quire-starter. As a workaround, I am able to download the files from the starter theme repo and add them to the themes directory manually in order to preview the site.

Add "Cite This Page" feature

As in previous catalogues, should automatically generate page-level citations in Chicago and MLA formats, using page and publication YAML.

Consider replacement options for smoothState.js

Quire currently uses smoothState.js to manage page transitions (both in request size and UX animation), but the library has now been inactive for a couple of years and is starting to cause some issues. See the discussion in https://github.com/gettypubs/quire-starter-theme/pull/24. Turbolinks is the primary option to replace smoothState, but others might be considered.

Add `q-class` shortcode

A simple shortcode to wrap a block of text in a Markdown document in a class for use with the custom.css file :

{{< q-class "custom-classname" >}}
    Your text here ...
{{< /q-class >}}

Produce a number of more complete JSON-LD outputs and have them evaluated

Quire includes a block of JSON-LD metadata in every page that's generated by the json-ld.html partial through information provided in publication.yml and in the page YAML. It's undergone modest testing, but could use more. In particular we should verify our particular use of the Getty vocabs.

Add icon handling to Resource Links

There are three types of "Resource Links" in the Quire content model: other-format, related-resource, and footer-link. They are used mainly in the menu, footer and about pages. As currently defined, each pf these items can have an icon attribute defined, which would typically be a small logo or icon image. Handling for this images needs to be implemented in the link-list.html partial.

Note that early attempts to do so using a model like that of q-figure shortcode that explicitly defines the base imagDir though .Site.Params. (as copied below) wasn't working, I think because the scope passed into the partial somehow negated calling .Site in the usual way

{{ if isset $.Site.Params "imagedir" }}
{{ $.Scratch.Set "imageDir" $.Site.Params.imageDir }}
{{ else }}
{{ $.Scratch.Set "imagedir" "" }}
{{ end }}

Define and document page type vs. layout vs. class

We need to make sure we're consistently using page type, layout and class in the theme templates, and that those uses are explained clearly in the documentation.

Implement core print styles

PDF output should include:

• Page numbers and running footers (incl. roman page numbering in frontmatter, and option for setting what chapter starts page 1)
• TOC with page numbers
• Margins for left and right pages
• Half title page
• Title page
• Copyright page
• Section breaks (with grid contents defaulting to splash page with title only, and list contents displaying the text list as in the online version)
• Front and backmatter page classes
• Figure classes for modest customization/differentiation from online version
• Full-bleed image option for object entries
• Potentially an option to output in two different sizes by using a variable control in variables.scss

Add error messaging on all shortcodes

All Quire shortcodes should have highly-visible error messaging built in, in order to give users more comprehensive understanding of why something isn't working. Without this feedback, Hugo will often still build the page, but leave the shortcode in as plaintext, which can be difficult to notice, and difficult to resolve once you do.

Error messages have been incorporated into the q-figure and q-figure-group shortcodes. An example of which can be seen in the screenshot here:

Add basic EPUB styles

Reading systems come with their own built-in styles (some more aggressively implemented than others) and so in most cases, EPUBs tend to work best with only minimal amounts of custom styling. In general the content structure should follow that of the PDF (with title page and the like). And these general styling items should be addressed:

• Basic heading treatments
• Use of $primary-color but being mindful of readers who may read in a night reading mode of light text on a dark background
• CSS code to keep images and captions from breaking across pages
• Hiding of grid contents lists (defaulting to a splash page of title only)

Print out Hugo error messages when running `quire preview` command

Currently, when running quire preview any Hugo error messages are suppressed. It would be preferable to show them to the user, as even a small change in any of the templates can break the Hugo build process, and for now users have no way of tracking down the issue except by stopping Quire and running hugo server instead.

Glossary

Create a Glossary of terms that need explanation. Some terms can be moved from current pages to the glossary file but others need to be identified by editors.

The glossary will be a yaml file so the terms can be displayed on pop-up windows with a shortcode.

Add a `quire stop` command

Even though you can stop the quire preview process with the standard Control-C in the Terminal, or by closing the window, I'm repeatedly finding in working with people at workshops and virtually that it's counterintuitive to remember that command. Let's add a simple quire stop command.

Address security vulnerabilities in dependencies

GitHub has recently started sending out warnings about potential security issues in repository dependencies. They can be accessed in the individual repositories on GitHub.com, in the Dependency Graph, under the Insights tab. Any existing vulnerabilities in both quire-cli and quire-starter-theme should be addressed. And new ones taken care of as they appear moving forward.

Implement `additional_references` as in Keep It Moving

In the book, Keep It Moving, we included an additional_references attribute in the page YAML, where users could list one or more short references to the bibliography.yml file, and they would be added in to the list of any other direct citations made in the text of the page through the q-cite shortcode, and so then output with the full bibliography at the end of the page. This might be useful to include in the core content model of Quire going forward.

Expand quire content to demonstrate all variations for testing

Ideally, we should have a content repository that shows all various uses of shortcodes, partials and page templates to use for testing as we're building new features. Ultimately the starter kit should be relatively clean, but for now probably easiest to use if for this testing content. Perhaps all of it goes in a test directory to keep it separate.

Add notes for "Tips" and "warnings"

Highlight advice and warning information on the documentation. Follow the example on https://developer.gnome.org/gdp-style-guide/2.32/gdp-style-guide.html#infodesign-18

In Quire, these notes should use a style different from the main text.

Add CC logos

When a user applies one of seven Creative Commons licenses to their publication, and defines the abbreviation attribute with the corresponding code from the list below, Quire should automatically include the correct CC logo in the layout (through the copyright.html partial), and in SVG form with css to color the fill as neccesary.

• "CC0"
• "CC BY"
• "CC BY-SA"
• "CC BY-ND"
• "CC BY-NC"
• "CC BY-NC-SA"
• "CC BY-NC-ND"

Add Next/Prev swiping for touch devices

Related to Issue #9 (next/prev keyboard navigation) we should also add next/prev swiping for touch devices. We've previously used hammer.js for this, but open to other approaches or tools.

Address cli and theme install warnings

A number of varying dependency warnings come up in the command line when installing quire-cli and when running quire install (which runs the install process on quire-starter-theme). I believe all of them are dependencies of our dependencies, but our goal should be to pro-actively manage them, both for ourselves, and in documentation available to our users. I believe the steps to take are:

• Update the dependencies if possible
• Eliminate or substitute any dependencies that can be
• Document those that can't be easily updated or replaced
• Document the process for handling future warnings

---

Sample install output from Mac:

theme-install-output--alpha12.txt
cli-install-output--alpha12.txt

Installation videos

Videos will help users to follow installation steps and see what is happening in the command line interface.

Rationalize baseURL and config.yml handling

Currently, there are an overwhelming five config files in the main project directory:

• config.yml
• config.build.yml
• config.dev.yml
• config.epub.yml
• netlify.toml

netlify.toml is obviously specific for a Netlify deployment, but at this stage, I don't think that should be so primary. Down the road it might be a more central part of Quire, but for now, if someone wants to deploy on Netlfy we can document the process of adding this file, and changing other settings. So, this one can go.

Of the remainder, config.yml is the main one, the other three YAML files are only to adjust specific baseURL, canonifyURLs, and relativeURLs values for different environments. Most critical is that when building EPUBs with the Quire CLI, the settings need to be:

baseURL: "localhost:1313"
canonifyURLs: true

So that's what's set in config.epub.yml, but I believe there's no reason those same settings couldn't also work for local development. The config.dev.yml file currently does nothing, so it seems to me that the epub and dev settings could be the same and that they could all live in the main config.yml file.

Finally, we have config.build.yml and this is where users could enter their specific URL depending on where they're ultimately deploying the site. And so the instructions on the config.yml file settings could be essentially, "Leave them alone".

And what of the URL?

Connected to this is our use of the main publication URL in a number of partials, particularly for site metadata and for the Cite This Page feature. The Quire content model says that a publication has a url (defined in publication.yml) and we could use that for all the partials: {{ .Site.Data.publication.url }} . Or, we could point those partials to {{ .Site.BaseURL }} which when building the site for deployment would be the baseURL in config.build.yml, and so would avoid duplicating the URL in both that file and in publication.yml. However, because the URL is output in content and so would be proofread and have an effect on the layout by means of its length you wouldn't want that changing during the development process. So, better to allow the duplication and use url with perhaps the baseURL being the fallback if url isn't set.

Pandoc file conversion tips

We have to extend the instructions to convert .doc files to Markdown using Pandoc in the "Pages & Plain Text" page.

Finish refinement of basic theme design

The Alpha 12 release came with a number of significant improvements to the theme design. A small punchlist of items remain to be addressed in a subsequent release:

• Splash pages
• Abstracts
• Quire page CSS class/element structure
• Bottom margin/padding for pages
• Unicode characters being replaced with emoji in iOS
• Icon PNG fallbacks (the ones there now are the old icon set)

Troubleshooting advice

We should provide troubleshooting tips for PC and Mac installations

Create evaluation protocol for beta testers

I've got a basic outline of our beta testing process in the wiki. As you'll see, once approved for the beta, testers will be asked to get started on their own first. We'll then do a evaluation of their experience up to that point, and then have a call with them to talk more specifically about their project and next steps. What we need to do is come up with a specific evaluation system for this first phase, after they've tried it out on their own. The evaluation might be an online survey form, an interview or conversation, or both, or something else altogether.

Here are some initial possible questions I jotted down quite some time ago:

• On a scale of 1 to 5, 1 being the easiest, how difficult was the process?
• Do you feel it worked as expected?
• How many times did you consult the documentation?
• Did you consult with anyone else or do any google searching?
• How would you describe the process to someone who was going to be doing it for the first time themselves?

I like the last one, but not sure how useful they all otherwise are. I think generally the questions we ask should be related to the steps taken (or better, skills learned) during the steps in the Getting Started chapter. The idea is to test where users run into trouble on their own, what they learn initially about Quire, and what questions they have in taking the next steps.

Anchor links don't behave as expected

Anchor links going to other pages and written in Markdown (such as [note 5](../catalogue/1/#fnref:5)) will go to the page, but not scroll to the appropriate anchor position. Similarly, the browser back button will change the URI in the address bar, but have no effect on the page position. Presumable both issues are related to Quire’s use of smoothState.js.

Add Next/Previous keyboard navigation

As in past publications, the right and left keyboard arrows should take you to the next and previous pages respectively.