From b598c52623d064b951b25222e817882ef5aa08cc Mon Sep 17 00:00:00 2001 From: Erin Cecele Dunigan Date: Wed, 31 May 2023 13:03:07 -0700 Subject: [PATCH 1/5] replace content with TK - main page --- content/docs-v1/fonts-customization.md | 120 +------ content/docs-v1/for-developers.md | 412 +----------------------- content/docs-v1/styles-customization.md | 152 +-------- content/docs-v1/zooming-images.md | 216 +------------ 4 files changed, 26 insertions(+), 874 deletions(-) diff --git a/content/docs-v1/fonts-customization.md b/content/docs-v1/fonts-customization.md index a6131009..daee4668 100644 --- a/content/docs-v1/fonts-customization.md +++ b/content/docs-v1/fonts-customization.md @@ -3,136 +3,28 @@ title: Font Customization weight: 6360 type: essay abstract: "Add external fonts to your publication" -menu: false -toc: false aliases: - /documentation/fonts-customization/ --- -Typography is an important element of style in your Quire publication. Quire allows different levels of font customization, from using the already embedded open license fonts in the default Quire theme (`themes/default`), to adding new external fonts. +TK ## Customize Fonts -Quire’s defualt theme includes three embedded, open license fonts: ["Noto Sans"](https://github.com/googlefonts/noto-fonts), ["Noto Serif"](https://github.com/googlefonts/noto-fonts), and ["IBM Plex Sans Condensed"](https://github.com/IBM/plex). You can adjust which fonts are used where in the "variables" file of your {{< q-def "theme" >}}, `themes/default/source/css/variables.scss`: - -```scss -$ibm-sans: 'IBM Plex Sans Condensed', sans-serif; -$noto-sans: 'Noto Sans', sans-serif; -$noto-serif: 'Noto Serif', serif; - -$quire-primary-font: null; // body and menu text -$quire-headings-font: null; // headings -$quire-footnotes-font: null; // footnotes and page backmatter -$quire-navigation-font: null; // navbar and next/prev buttons -``` - -The `$quire-primary-font`, `$quire-headings-font`, `$quire-footnotes-font`, and `$quire-navigation-font` variables are listed first with "null" values. Left as is, Quire will use the default fonts as specified elsewhere in the templates. You can choose your own combinations by using a defined font in place of "null": - -```scss -$quire-headings-font: $noto-serif; -``` +TK ## Add a New Font -{{< q-class "box warning" >}} - -- Any font you add to your project should be under an open license, or you should have an explicit license to use it. While licensed fonts may offer variety, using them often means paying fees and tracking usage. Additionally, if you are using GitHub to publicly share your Quire project, licensed fonts should **never** be included in your repository without also being listed on your `.gitignore` file, as this will expose the files to other users. - -{{< /q-class >}} - -For open license fonts, [Google Fonts](https://fonts.google.com/) is a great source, but other more artisanal options abound, like the faces from the [League of Moveable Type](https://www.theleagueofmoveabletype.com/) or even [Cooper Hewitt’s own open source font](https://www.cooperhewitt.org/open-source-at-cooper-hewitt/cooper-hewitt-the-typeface-by-chester-jenkins/). For more free fonts and for thoughtful ideas about their use, Jeremiah Shoaf’s [*The Definitive Guide to Free Fonts*](https://www.typewolf.com/free-fonts) is worth the purchase price. - -The steps to adding new fonts to your publication are: +TK ### 1. Prepare Your Font Files and Add Them to Your Project -It’s recommended to include your font files in multiple file formats in order to increase browser compatibility. Ideally, you will have each of your fonts in the following formats: `.eot`, `.woff2`, `.woff`, and `.ttf`. If this is not the case, you can use a free webfont generator, like the one from Font Squirrel, to produce these various formats from a single source. - -All the fonts you’d like to add should go in a folder named after the font, and all should be named consistently. We recommend the following format with lowercase and no spaces: - -```md -📁 cooper-hewitt - 📄 cooper-hewitt-bold.eot - 📄 cooper-hewitt-bold.ttf - 📄 cooper-hewitt-bold.woff - 📄 cooper-hewitt-bold.woff2 - 📄 cooper-hewitt-bolditalic.eot - 📄 cooper-hewitt-bolditalic.ttf - 📄 cooper-hewitt-bolditalic.woff - 📄 cooper-hewitt-bolditalic.woff2 -``` - -In your `themes/default` folder, all fonts are stored in `source/fonts`. Move your folder of fonts there. - -``` -cooper-hewitt -``` - -If you are using GitHub, and this is a licensed font, or a font you don’t otherwise want available to anyone outside your project, add a line to your project’s `.gitignore` file to make sure the fonts are not added to the git record. - -You will continue to have the fonts available in your local copy of your project, but anyone working on a clone or fork of your repository will have to manually add your font files to their local copy for them to appear in the project properly when they preview or build the site. - -When you ultimately host the final site on a web server, the fonts will be included in the built files and will need to be included in the package on the web server. Files hosted this way are not readily accessible to non-technical users, but are still public. For another layer of protection, font files could be assigned more generic names (ie., `f1-bld.ttf` instead of `cooper-hewitt-bold.ttf`). For complete protection of licensed/proprietary font files, other solutions should be sought. +TK ### 2. Add Font Information to Your Stylesheets -Open the file `source/css/fonts.scss`. Each font in your font folder should have its own `@font-face` entry, as the examples in this file demonstrate. - -```css -@font-face { - font-family: "Cooper Hewitt"; - src: url("../fonts/cooper-hewitt/cooper-hewitt-bold.eot"); - src: url("../fonts/cooper-hewitt/cooper-hewitt-bold.eot?#iefix") format("embedded-opentype"), - url("../fonts/cooper-hewitt/cooper-hewitt-bold.woff2") format("woff2"), - url("../fonts/cooper-hewitt/cooper-hewitt-bold.woff") format("woff"), - url("../fonts/cooper-hewitt/cooper-hewitt-bold.ttf") format("truetype"); - font-weight: 700; - font-style: normal; -} -``` - -- The `font-family` name is what you will use to call the font in your stylesheets. It is typically in title case, and can include spaces. The `font-family` name should be the same for all weights and styles of font you are adding. Meaning, all `""Cooper Hewitt""` not `""Cooper Hewitt" Bold"` or `""Cooper Hewitt" Light Italic"`. - -The individual weights and styles are instead specified with the `font-weight` and `font-style` properties. - -- The `font-weight` should be an integer set to match named weight of your font. Following the table below, a “Light” font would have a `font-weight` of 200. A “Bold” font would have a `font-weight` of 700. - -| `font-weight` | Font name | -| --- | --- | -| 100 | Extra Light or Ultra Light | -| 200 | Light or Thin | -| 300 | Book or Demi | -| 400 | Normal or Regular | -| 500 | Medium | -| 600 | Semibold, Demibold | -| 700 | Bold | -| 800 | Black, Extra Bold or Heavy | -| 900 | Extra Black, Fat, Poster or Ultra Black | - -- The `font-style` will be either `normal` or `italic`. +TK ### 3. Use Your New Font -With the font files included in the `source/fonts` folder, and all the matching `@font-face` entries saved to the `source/css/fonts.scss` file, you can now use your font anywhere in your site CSS with `font-family`. - -```css -h1 { - font-family: "Cooper Hewitt"; -} -``` - -Typically, you’ll want to change fonts across the project. For instance, making all the main body copy a new font, or all the headings. This can be done in the `source/css/variables.scss` file that we describe in the [Customize fonts section](#customizing-fonts): - -To replace all `$sans-serif` uses with a new font: - -```scss -$sans-serif: "Cooper Hewitt", Helvetica, sans-serif; -``` - -Or to leave the existing `$sans-serif` and just make all the primary font be our new one: - -```scss -$family-primary: "Cooper Hewitt", Helvetica, sans-serif; -``` - -The rules about fallback fonts described in the [Customize fonts section](#customizing-fonts) above also apply to the new fonts. +TK diff --git a/content/docs-v1/for-developers.md b/content/docs-v1/for-developers.md index 038dbefb..5b8a4efc 100644 --- a/content/docs-v1/for-developers.md +++ b/content/docs-v1/for-developers.md @@ -3,15 +3,11 @@ title: For Developers weight: 6040 type: essay abstract: "API docs and Quire repository guide" -menu: false -toc: false aliases: - /documentation/for-developers/ --- -Quire is in a limited beta and not yet released as open-source software. For a free license to use Quire for your publication projects, and for additional access to support, [please sign up](https://docs.google.com/forms/d/e/1FAIpQLScKOJEq9ivhwizmdazjuhxBII-s-5SUsnerWmyF8VteeeRBhA/viewform) - -Quire is centered around the static site generator, [Hugo](https://github.com/gohugoio/hugo). Quire's command-line interface is written in JavaScript and requires [Node.js LTS](https://nodejs.org/en/) to run. +TK ## Repositories @@ -19,418 +15,22 @@ Quire is centered around the static site generator, [Hugo](https://github.com/go https://github.com/thegetty/quire -This repo contains the command-line interface for Quire, default starter content used as placeholder content when starting a new Quire project, and a default theme designed to broadly cover a full range of use-cases and demonstrate the range of Quire's content model. +Quire’s primary repository, with the command-line interface and 11ty template packages ### quire-docs https://github.com/thegetty/quire-docs -This repo is specifically for the Quire website and documentation. +This repository is specifically for the Quire website and documentation. ## Configuration -General configuration options for a project. See [*Configure Hugo*](https://gohugo.io/getting-started/configuration/) for more options and information. - -Location: `config.yaml`, or any of the environment and format specific config files found in the `config` directory - -Type: Object - -| Object Properties | Expected Value | Description | -| --- | --- | --- | -| `baseURL` | url | The base url for your project. | -| `blackfriday` | [object](#blackfriday) | Options for Blackfriday, Hugo’s markdown renderer. Quire v0.18.0 and below. See below. | -| `buildDrafts` | | | -| `canonifyURLs` | boolean | Converts all internal links to being in complete canonical format. Default is `false`. | -| `disableKinds` | | | -| `footnoteReturnLinkContents` | string | Controls the appearance of the link added to the end of footnotes. Default is "↩". | -| `googleAnalytics` | | | -| `languageCode` | | | -| `markup` | [object](#markup) | Options for Hugo’s markdown rendering. Quire v0.19.0 and above. See below. | -| `metaDataFormat` | "yaml", "toml", "json" | Default is "yaml". | -| `params` | [object](#params) | Additional parameters for Quire. See below. | -| `pluralizeListTitles` | | | -| `publishDir` | | | -| `relativeURLs` | boolean | Keeps all internal links relative. Default is `true`. | -| `title` | | | -| `theme` | url/id | The name of the theme, in the `theme` directory you’re using. Quire starter kit default is `quire-base-theme`. | - -### `blackfriday` - -Configuration for the [Blackfriday](https://gohugo.io/getting-started/configuration-markup#blackfriday) markdown rendering engine. - -Location: `config.yaml`, or any of the environment and format specific config files found in the `config` directory - -Type: Object - -Compatibility: Quire v0.18.0 and below - -| Object Properties | Expected Value | Description | -| --- | --- | --- | -| `fractions` | boolean | When set to `true` any numbers separated by a slash are automatically converted to fractions. Default is `false`. Though even then 1/4, 1/2 and 3/4 are still converted. Recommend always using proper unicode fractions: ¼, ½, ¾, ⅛, ⅜, ⅝, ⅞. | -| `hrefTargetBlank` | boolean | When set to true, any Markdown links to external pages and resources will open in a new tab/window for the user. | - -### `markup` - -Configuration for the markdown rendering engine. See [Hugo’s Markup Configuration](https://gohugo.io/getting-started/configuration-markup/) for more options and information. - -Location: `config.yaml`, or any of the environment and format specific config files found in the `config` directory - -Type: Object - -Compatibility: Quire v0.19.0 and above - -| Object Properties | Expected Value | Description | -| --- | --- | --- | -| `goldmark.renderer.unsafe` | boolean | "true" (default) or "false", allows the inclusion of HTML markup in markdown pages. | - -### `params` - -Quire-specific project parameters. - -Location: `config.yaml`, or any of the environment and format specific config files found in the `config` directory - -Type: Object - -| Parameter | Expected Value | Description | -| --------- | -------------- | ----------- | -| `runTests` | boolean | Turn on or off the built-in tests that check for certain common errors and post error messages in the CLI output. | -| `searchEnabled` | boolean | Turn on or off the built-in text search capability for users. | -| `licenseIcons` | boolean | Whether or not to display Creative Commons license icons. | -| `pageLabelDivider` | string | ". " default, determines the text/spacing to be inserted between page .label and page .title. | -| `citationPageLocationDivider` | string | ", " default, determines the text/spacing to be inserted between the citation and the page number in the q-cite shortcode. | -| `displayBiblioShort` | boolean | Whether a bibliography generated with the q-cite or q-bibliography shortcodes should display the short form of the reference, along with the long. | -| `biblioHeading` | | | -| `imageDir` | string | "img" default, the directory in the `/static/` directory where you put your images. | -| `menuClass` | "brief", "list" | "list" is the default, "brief" will show only top-level pages and sections, no sub-sections. | -| `prevPageButtonText` | string | "Back" default. | -| `nextPageButtonText` | string | "Next" default. | -| `entryPageSideBySideLayout` | boolean | Entry pages can have a side-by-side layout with image on the left and text on the right, this can be controlled by `class: side-by-side` in the page YAML, or globally with this parameter. | -| `entryPageObjectLinkText` | string | "View in Collection" default. | -| `figureLabelLocation` | "on-top", "below" | Whether the figure label is "on-top" of the image in the upper left corner, or "below" it with the caption. | -| `figureModal` | boolean | If figures should be clickable to open into a full-screen modal window. | -| `figureModalIcons` | boolean | Whether to display icons with the figure modal links. | -| `figureZoom` | boolean | Whether figures should zoom or not inside the modal. | -| `citationPopupStyle` | "icon", "text" | Displays the citation pop-up links with an icon, or without. | +TK ## Publication API -Location: `publication.yaml` - -Type: Object - -| Object Properties | Expected Value | Description | -| --- | --- | --- | -| `title` | string | The title of your publication. | -| `subtitle` | string | The subtitle of your publication. | -| `short_title`[\*](#asterisked) | string | A short version of your title, primarily for use in navigation elements with limited space. | -| `reading_line` | string | An additional title line for your publication. | -| `url`[\*](#asterisked) | url | The full URL of your final publication. | -| `pub_type` | "book", "journal-periodical", "other" | Can be one of three values. Determines how key search-engine metadata is defined. | -| `pub_date` | YYYY-MM-DD | The first date your publication will be released. | -| `language` | 2-letter ISO 639-1 language code(s) | Taken from the the list at https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes. List multiple languages using a comma-separated list. | -| `identifier` | [object](#identifier) | See below. | -| `publisher` | [array](#publisher) | See below. | -| `contributor` | [array](#contributor) | See below. | -| `contributor_as_it_appears` | string | | -| `promo_image` | url | | -| `description` | [object](#description) | See below. | -| `subject` | [array](#subject) | See below. | -| `copyright` | string | | -| `license` | [object](#license) | See below. | -| `resource_link` | [array](#resource_link) | See below. | -| `revision_history` | [array](#revision_history) | See below. | -| `repository_url` | url | A public repository of the source code and revision history for the publication. | -| `series_periodical_name`[\*](#asterisked) | string | | -| `series_issue_number` | string | | - -### `publisher` - -Location: `publication.yaml` - -Type: Array - -| Item Attributes | Expected Value | Description | -| --- | --- | --- | -| `name` | string | Name of the publisher. | -| `location` | string | Publisher location, city. | -| `url` | url | Publisher homepage. | -| `logo` | | | - -### `description` - -Location: `publication.yaml` - -Type: Object - -| Object Properties | Expected Value | Description | -| --- | --- | --- | -| `one_line` | string | | -| `full` | string | | -| `online`[\*](#asterisked) | string | The `online` and `pdf_ebook` fields allow you to add additional text to the `full` description that is specific to either the online, or the PDF/EPUB/MOBI editions and will only show up there. For instance, in order to point to special features in one or the other of the formats. | -| `pdf_ebook`[\*](#asterisked) | string | | - -### `subject` - -Location: `publication.yaml` - -Type: Array - -| Item Attributes | Expected Value | Description | -| --- | --- | --- | -| `type` | "keyword", "bisac", "getty" | | -| `name` | string | | -| `identifier` | string | | - - -### `license` - -Location: `publication.yaml` - -Type: Object - -| Object Properties | Expected Value | Description | -| --- | --- | --- | -| `name` | string | Name of the license. | -| `abbreviation` | | If using a Creative Commons licenses, should match one of the seven available options: "CC0", "CC BY", "CC BY-SA", "CC BY-ND", "CC BY-NC", "CC BY-NC-SA", or "CC BY-NC-ND". | -| `url` | url | Link to the license text. | -| `scope` | "text-only", "full", "some-exceptions" | | -| `icon`[\*](#asterisked) | url | | -| `online_text` | string | Markdown okay. Will override the automatically generated license text for the online edition only. | -| `pdf_ebook_text` | string | Markdown okay. Will override the automatically generated license text for the PDF and e-book editions only. | - -### `resource_link` - -Location: `publication.yaml` - -Type: Array - -| Item Attributes | Expected Value | Description | -| --- | --- | --- | -| `name` | string | How the link will be named. | -| `type` | "other-format", "related-resource", "footer-link" | | -| `media_type` | string | Taken from the list at https://www.iana.org/assignments/media-types/media-types.xhtml. | -| `link_relation` | string | Taken from the list at https://www.iana.org/assignments/link-relations/link-relations.xhtml. | -| `url` | url | URL to web resource or to download. | -| `identifier`[\*](#asterisked) | [object](#identifier) | See below. | -| `file_size_mb`[\*](#asterisked) | integer | For downloads, file size in megabytes. Often appended to `name` in the interface, depending on your theme. | -| `icon`[\*](#asterisked) | url | | - - -### `revision_history` - -Location: `publication.yaml` - -Type: Array - -| Item Attributes | Expected Value | Description | -| --- | --- | --- | -| `date` | YYYY-MM-DD | | -| `summary`[\*](#asterisked) | list | | - -### `identifier` - -Location: `publication.yaml`, in any `.Page.Params.`, or in any `resource_link` - -Type: Object - -| Item Attributes | Expected Value | Description | -| --- | --- | --- | -| `isbn` | 10- or 13-digit ISBN | For use with `pub-type` of "book". ISBNs can be purchased individually or in packages at http://www.isbn.org/. | -| `issn` | 8-digit ISSN | For use with `pub-type` of "journal-periodical". ISSNs can be requested through https://www.issn.org/. | -| `doi`[\*](#asterisked) | string | Not yet implemented. | -| `uuid`[\*](#asterisked) | string | Not yet implemented. | -| `url` | | Possibly replacing `url` in general Publication level?? | - -### `contributor` - -Location: `publication.yaml` or in any `.Page.Params.` - -Type: Array - -| Item Attributes | Expected Value | Description | -| --- | --- | --- | -| `id` | string | Numbers and lowercase letters only, with no spaces or special characters ("001", "fig-01a", "bird-picture", etc). | -| `type` | "primary", "secondary", or user choice | | -| `first_name` | | All contributors must have either a first and last name, or a full name defined. | -| `last_name` | | | -| `title` | | | -| `affiliation` | | | -| `url` | url | | -| `bio` | | Markdown okay. | -| `pic` | url | Should be the file name of a JPG, PNG or GIF image (`fig01.jpg`). Avoid using spaces or special characters, and if it’s in a sub-folder within the main `img` directory (which is defined by the `imageDir` parameter in the `config.yaml` file), it should include that sub-folder name as well (`contributors/fig01.jpg`). | -| `full_name` | | | -| `file_as` | | | - -### `figure_list` - -Location: `figures.yaml` - -Type: Array - -| Item Attributes | Expected Value | Description | -| --- | --- | --- | -|`id` | string | Numbers and lowercase letters only, with no spaces or special characters ("001", "fig-01a", "bird-picture", etc). | -| `src` | url | Should be the file name of a JPG, PNG or GIF image (`fig01.jpg`). Avoid using spaces or special characters, and if it’s in a sub-folder within the main `img` directory (which is defined by the `imageDir` parameter in the `config.yaml` file), it should include that sub-folder name as well (`comparatives/fig01.jpg`). | -| `alt` | string | For accessibility, all images should have alternative text descriptions. ([Tips on crafting good alt text.](https://webaim.org/techniques/alttext/)) Only ever leave blank if the image is purely decorative. | -| `caption` | string | The caption to appear below the figure. Special characters are allowed. Use Markdown for formatting. | -| `credit` | string | Follows the caption. Markdown allowed. | -| `media_type` | "youtube", "vimeo" | Currently supports video hosted on YouTube or Vimeo. (May eventually expand to HTML5 video, audio, and Soundcloud, and others.) When a `media_type` is defined, a `media_id` must be as well. For video, it is also recommended that an image `src` still be used (presumably being a screenshot from the video) so as to provide a fallback for PDF and EPUB output. | -| `media_id` | string | The ID of the video resource on YouTube or Vimeo. For example, in the URL [https://www.youtube.com/watch?v=VYqDpNmnu8I](https://www.youtube.com/watch?v=VYqDpNmnu8I), the `media_id` would be `VYqDpNmnu8I`; and in https://vimeo.com/221426899 it is `221426899`.| -| `aspect_ratio` | "standard", "widescreen" | For use with video `media_type`s to properly scale video embeds. When no value is provided, the default is "widescreen". | -| `label` | string | | -| `download` | boolean | If "true", download icon will be added to image viewer, allowing users to easily download the image file. Currently only implemented in the page `type: entry` image viewer. Default is "false". | - - -### `entries` - -Location: `references.yaml` - -Type: Array - -| Item Attributes | Expected Value | Description | -| --- | --- | --- | -| `id` | string | | -| `short` | string | The short form of the citation, ie., Brown 1984. Markdown okay. | -| `full` | string | The full form of the citation. Markdown okay. | -| `sort` | string | | - - -### `object_list` - -Location: `objects.yaml` - -Type: Array - -| Attribute | Expected Value | Description | -| --- | --- | --- | -| `id` | string | Required. Used to reference objects from entry pages. Should be numbers and lowercase letters only, with no spaces or special characters (`001`, `fig-01a`, etc). | -| `figure` | [array](#figure_list) | A list of one or more images of the object. It is recommended that this list be only of `id` values corresponding with `id`s in your project’s `figures.yaml` file. | -| `link` | url | A URL link to a page with more/current information on the object. Usually the object in the museum’s online collection pages. | -| `date_start`, `date_end` | integer | Reserved for future use in Quire. | -| `dimension_width`, `dimension_height`, `dimension_depth` | integer | Reserved for future use in Quire. | - -Objects also support arbitrary attributes, which might include `title`, `artist`, `collection`, etc. Those added will be output in a table on collection catalogue entry pages. The ordering of the display can be controlled with `object_display_order` in `objects.yaml`. See [*Guide on Collection Catalogues*](/docs-v1/collection-catalogues/). - -## Page API - -Location: Any Markdown page in the `/content/` directory. - -Type: Object - -| Attribute | Expected Value | Description | -| --- | --- | --- | -| `label` | string | A label for the page “Chapter 1”, “2”, “III”, etc. | -| `title` | string | | -| `subtitle` | string | | -| `short_title` | string | Used in navigation items where a long title would be too unwieldy. | -| `type` | "page" (default), "essay", "entry", "cover", "contents", "splash", or "data" | See [*Define Page Types*](/docs-v1/pages/#define-page-types) for examples | -| `class` | string | Can accept any string, which will be included as a class in the main page element to facilitate style customization. A number of pre-defined classes also exist in the [Quire Default Theme](https://github.com/thegetty/quire/tree/main/themes/default). Pages with `type: contents` can have class `list` (default), `brief`, `abstract`, or `grid`. Pages with `type: entry` can have class `landscape` (default) or `side-by-side`. | -| `weight` | integer | Controls ordering of pages in the publication. | -| `object` | [array](#object_list) | See [*Catalogue Entries*](/docs-v1/collection-catalogues/). | -| `contributor` | [array](#contributor) | See [*Contributors*](/docs-v1/contributors/). | -| `contributor_byline` | boolean | | -| `abstract` | string | Markdown okay. | -| `slug` | url path | Will change the URL of the page. Or use a period `.` to make the URL be the directory name (homepage). Read more in the [*Page Types & Structure*](/docs-v1/pages/#creating-section-landing-pages) chapter of this guide.| -| `toc` | boolean | Default is "true". Page will not display in contents page if "false". | -| `menu` | boolean | Default is "true". Page will not display in menu if "false". | -| `online` | boolean | Default is "true". Page will not display in the online edition if "false". | -| `pdf` | boolean | Default is "true". Page will not display in the PDF edition if "false". | -| `epub` | boolean | Default is "true". Page will not display in either the EPUB or MOPBI e-book editions if "false". | -| `image` | url | | - -Pages with `type: contents` can have class `list` (default), `brief`, `abstract`, or `grid`. Pages with `type: entry` can have class `landscape` (default) or `side-by-side`. +TK ## Shortcodes API -### `q-class` - -Used for styling. Wrapping any Markdown text in this shortcode will wrap it in a `
` with the given class name in the HTML output. - -`{{}} {{}}` - -| Positional Parameter[†](#positional) | Expected Value | Description | -| --- | --- | --- | -| `0` (class name) | string | String without spaces or special characters to be used as a class for CSS styling. | - -### `q-bibliography` - -Generates a bibliography from the entries in the project's `bibliography.yaml` file. See [*Citations & Bibliographies*](/docs-v1/citation-bibliographies/). - -`{{}}` - -| Parameter | Expected Value | Description | -| --- | --- | --- | -| `sort` | string | Optional. Value can be any string that matches a key in the entires under `entries` of the `references.yaml` file, to indicate which key to alphabetically sort the output bibliography by. Without `sort` the default sort is on "full". | - -### `q-cite` - -Adds a linked Author Date citation reference to the text, and a hover pop-up with the full citation text. It also adds the citation to a map of cited works, which can then be output as a page-level bibliography on essay and entry type pages. See [*Citations & Bibliographies*](/docs-v1/citation-bibliographies/). - -`{{}}` - -| Positional Parameter[†](#positional) | Expected Value | Description | -| --- | --- | --- | -| `0` (author date reference) | string | Should exactly match an `id` value under `entries` in the `references.yaml` file. Typically something like "Jones 1974". | -| `1` (page number) | string | Optional. A page number of the specific citation. Will be appended to the citation text with a text divider defined by `citationPageLocationDivider` in `config.yaml` | -| `2` (display text)| string | Optional. Alternate text that should be displayed instead of the default Author Date provided in the first parameter. | - -### `q-contributor` - -Can be used to create a page of contributor biographies, a section of bios for a single page, a simple list of contributors, a byline for a particular page, or other similar outputs. See [*Contributors*](/docs-v1/contributors/). - -`{{}}` - -| Parameter | Expected Value | Description | -| --- | --- | --- | -| range | "page", "all", or string | Defines which contributors to include. An arbitrary value matching a contributor type such as "primary" or "secondary" may also be used. | -| format | "initials", "name", "name-title", "name-title-block", "bio" | Defines what format the list should take. | -| align | "left" (default), "center", "right" | Optional. Defines how the output text will be aligned. | - -### `q-figure` - -Inserts a formatted figure image, label, caption and credit line. If using a `data/figures.yaml` file, only an `id` parameter is required for this shortcode. If other values supplied directly in the shortcode they will override any corresponding values in the `data/figures.yaml`. See [*Figure Images*](/docs-v1/figure-images/) and [`figure_list`](#figure_list) above. - -`{{}}` - -| Parameter | Expected Value | Description | -| --- | --- | --- | -|`id` | string | Spaces or special characters should not be used and will be stripped out. When used in a shortcode *without* a corresponding `src` parameter, the shortcode will look for a matching `id` in the project’s `data/figures.yaml` file. When used in a shortcode *with* a corresponding `src` parameter, this will create an `id` for the image markup that can be used to link to the image directly (`mypublication.com/chapter01/#fig-3`) and ignores any potentially corresponding information in the `data/figures.yaml` file. | -| `src` | url | Should be the file name of a JPG, PNG or GIF image (`fig01.jpg`). Avoid using spaces or special characters, and if it’s in a sub-folder within the main `img` directory (which is defined by the `imageDir` parameter in the `config.yaml` file), it should include that sub-folder name as well (`comparatives/fig01.jpg`). If your project uses `data/figures.yaml` file, you shouldn’t use a `src` parameter in the shortcode as it will override all other information. | -| `alt` | string | For accessibility, all images should have alternative text descriptions. ([Tips on crafting good alt text.](https://webaim.org/techniques/alttext/)) Only ever leave blank if the image is purely decorative. | -| `caption` | string | The caption to appear below the figure. Special characters are allowed. Use Markdown for formatting. | -| `credit` | string | Follows the caption. Markdown allowed. | -| `label` | boolean | Default is set to `true`. `true` will add a label to the caption, such as "Figure 1.3", `false` will remove the label. The global label setting is in the `config.yaml` file under the parameter `figureLabels`. | -| `class` | `is-pulled-right`, `is-pulled-left`, `is-full-width`, `is-centered-small` | Sets the style of the figure image. | - -### `q-figure-group` - -Like `q-figure`, but with handling for multiple images at once. See [*Figure Images*](/docs-v1/figure-images/) and [`figure_list`](#figure_list) above. - -`{{}}` - -| Parameter | Expected Value | Description | -| --- | --- | --- | -|`id` | string | One or more comma-separated `id`s that match corresponding values in the project’s `data/figures.yaml` file. | -| `caption` | string | The caption to appear below the figure group. Special characters are allowed. Use Markdown for formatting. Overrides any caption information provided in `data/figures.yaml`. | -| `credit` | string | Follows the caption. Markdown allowed. Overrides any caption information provided in `data/figures.yaml`. | -| `label` | boolean | Default is set to `true`. `true` will add a label to the caption, such as "Figure 1.3", `false` will remove the label. The global label setting is in the `config.yaml` file under the parameter `figureLabels`. If a `caption` is also provided in the shortcode, the labels will be applied on their own directly under each image in the group, rather than as part of the caption. | -| `class` | `is-pulled-right`, `is-pulled-left`, `is-full-width`, `is-centered-small` | Sets the style of the group of figures overall. | -| `grid` | `1`, `2`, `3`, `4`, `5`, `6` | Determines the horizontal width (in number of images) of the image grid. If no grid is set, the images will stack on top of one another vertically. | - -### `q-figure-zoom` - -Uses IIIF to add high resolution images with deep-zoom capabilities. See [*Zooming Images with IIIF*](/docs-v1/zooming-images/) - -| Parameter | Expected Value | Description | -| --- | --- | --- | -| id | string | | - -
- -## Notes - -* Attributes with an asterisk are in the process of being reviewed as they may not be currently being used and/or may be deprecated. - -† Positional parameters are included in shortcodes without a name defining them. See [`q-class`](#q-class), and [`q-cite`](#q-cite). - -
+TK \ No newline at end of file diff --git a/content/docs-v1/styles-customization.md b/content/docs-v1/styles-customization.md index 58583b85..fe208fc8 100644 --- a/content/docs-v1/styles-customization.md +++ b/content/docs-v1/styles-customization.md @@ -3,165 +3,21 @@ title: Style Customization weight: 6340 type: essay abstract: "Alter look and feel with custom styles and themes" -menu: false -toc: false aliases: - /documentation/styles-customization/ --- -The look and feel of your Quire publication can be customized at four different levels of complexity: - - 1. Changing style {{< q-def "variables" >}} in the {{< q-def "theme" >}} - 2. Adding new style rules to the `custom.css` file - 3. Overriding specific theme {{< q-def "templates" >}} with your own custom version - 4. Creating an entirely new Quire theme. +TK ## Change the Theme Style Variables -When you first start a new Quire project by running the command `quire new`, a default theme is installed in the project's `themes` directory. This default theme includes a number of default style variables that will let you update text and background colors, some element sizes, fonts, paragraph indents, and more. This allows relatively easy customization without the need to dig into the stylesheets and CSS markup. A [complete list of these variables](/docs-v1/variables) includes information about the customizations available. - -To find the variables, open the `themes/default` directory, navigate to the `source` sub-directory, and then `css`, and open the file called `variables.scss`. - -{{< q-figure id="1.12" >}} - -The variables are prefixed with a dollar sign and are descriptive of what they control. For instance `$quire-navbar-background-color` is the background color of the navigation bar at the top of every page. To make it red, you could enter: - -```css -$quire-navbar-background-color: red; -``` - -Colors are expressed a number of different ways, none of which are better or more supported than the others, so you can use your preference. Most common are: - -- The standard 140 {{< q-def "Color Keywords" >}} such as `red`, `royalblue`, and `honeydew` -- The many possible {{< q-def "HEX color values" >}} like `#FF0000`, `#4169E1`, and `#F0FFF0` -- {{< q-def "RGB Color Values" >}} like `rgb(255, 0, 0)`, `rgb(65, 105, 225)`, and `rgb(240, 255, 240)` - -{{< q-class "box warning" >}} -- You must have the `quire preview` command running in your command-line interface to see changes you make to the `variables.scss` file. You may also need to refresh your browser page or clear the browser cache to get the style changes to fully load. -{{< /q-class >}} +TK ## Add Custom Styles -In your project’s `static` directory, there is a `css` directory with a blank `custom.css` file. - -{{< q-figure id="1.13" >}} - -Any {{< q-def "CSS" >}} you add here, will be added to your site’s styles. For example, let’s say you’d like a particular line of text in one of your {{< q-def "Markdown" >}} files to be red. You could wrap that text in `` HTML tags and give it a class. - -```html -This text should be red -``` - -And then in your `custom.css` file, add a style rule for that class: - -```css -.red-text { - color: red; -} -``` - -Custom {{< q-def "CSS" >}} like this can also be used in conjunction with the `q-class` shortcode. While you can add `` HTML tags within lines and paragraphs of text, in Markdown you can’t do the same with `
` or `
` tags across multiple paragraphs. Instead, you can use the `q-class` shortcode to assign any class to all the Markdown within the opening and closing shortcode tags. - -```go -{{}} - -This entire paragraph should be red. - -As should the paragraph after it. - -{{}} -``` - -Styles added to the `custom.css` file will also override any existing styles already in use in your {{< q-def "theme" >}}. For example, the following option would apply the style to any element with a {{< q-def "class" >}} of `"title"` anywhere in your publication. - -```css -.title { - color: red; -} -``` - -To determine the selectors for any {{< q-def "element" >}} in your browser of choice with your publication previewing, control-click (Mac) or right click (PC) on the element and select "Inspect element". This will show you the HTML markup for your site, along with all the {{< q-def "class" >}} names and elements, and even the styles that are currently being applied to that {{< q-def "element" >}}. - -The more specific you can be with your {{< q-def "CSS selectors" >}}, the more likely the style will only be applied to the specific element you want. For example, if you wanted the page title on a specific page to be a different color than the titles on the rest of the pages, you could determine the {{< q-def "CSS selector" >}} for that element on that page and apply a style rule to it without changing the styles on any other element or page. This example limits the style to the title in the page header of that one page: - -```css -#chapter-one .quire-page__header .title { - color: red; -} -``` - -In the above example, we are selecting the element with a {{< q-def "class" >}} of `"title"` that is inside an element with the class of `"quire-page__header"` (both of which start with a period `.` to indicate {{< q-def "class" >}}), that is inside an {{< q-def "element" >}} (in this case an element representing the page itself) with an {{< q-def "id" >}} of `"#chapter-one"` (which starts with a hashmark to indicate id). - -{{< q-class "box tip" >}} - -- In Quire, page ids are unique, and can be found on the `
` element that has the {{< q-def "class" >}} `"quire-primary"`. By using the {{< q-def "id" >}} in your custom {{< q-def "CSS" >}}, you are targeting only that page, not all `"quire-primary"` {{< q-def "element" >}}s throughout your publication. - -{{< /q-class >}} - -{{< q-class "box tip" >}} - -- Exceptionally, if somewhere there is a more specific {{< q-def "CSS selector" >}} that’s applying a style to an element, it will override the less specific one — even if it’s in your `custom.css` file. If you are trying to apply a more global style change like this and you find it’s not working, it may be because your {{< q-def "CSS selector" >}} is too generic and there is a more specific rule elsewhere in your theme’s styles that is overriding your more general one. The "Inspect element" tool will point to what combination of CSS selectors are actually applying the final style as it’s seen in the browser window. - -{{< /q-class >}} +TK ## Override Theme Templates -{{< q-def "CSS" >}} changes like those mentioned above are best for restyling existing elements. If you’d like to make a more structural change, say, to rearrange elements on the page, or add new elements altogether, you’ll need to alter the {{< q-def "template" >}} files that come in the {{< q-def "theme" >}}. That said, other than changing the {{< q-def "Variables" >}} in `variables.scss` file, as described above, it’s usually best not to make other changes directly in the theme itself. By not doing so, it’s easier to update your theme or switch out other themes later, not to mention easier to undo changes you’ve made. - -For modest changes to the theme {{< q-def "templates" >}}, we recommend creating new override files. Much like the `custom.css` file can be used to override styles in the project theme, you can also have files to override templates. There are none in the default starting project, so you’ll need to start creating a new `layouts` directory folder in the main directory of your project. Any files you put in this `layouts` directory will override the corresponding files in the `layouts` directory of your theme. This includes page templates, partial templates, and shortcodes. - -For example, let’s say you want to customize the layout of all the pages in your project with the `type` of `"essay"`. In the theme `layouts` directory you’ll find that there’s a sub-directory called `essay` with a file in it called `single.html`. This is the template that controls the `"essay"` pages. You can see there’s a page header, an abstract, the main content `(.Content)` of the {{< q-def "Markdown file" >}}, and a page bibliography. - -```go -{{ define "main" }} -
- - {{ partial "page-header.html" . }} - - {{ if .Params.abstract }} - {{ partial "page-abstract.html" . }} - {{ end }} - -
-
-
- {{ .Content }} - {{ partial "page-bibliography.html" . }} -
-
-
- -
-{{ end }} -``` - -If you copy the `essay` subdirectory and its `single.html` file into the new `layouts` directory in your project’s main directory, this copy will override anything in the {{< q-def "theme" >}}. So, if you delete the bibliography and rearrange the header and abstract in the copied file, that’s what Quire will use when building the site. It only changes the style of the header and abstract of your pages while the bibliography style remains intact. - -```go -{{ define "main" }} -
- - {{ if .Params.abstract }} - {{ partial "page-abstract.html" . }} - {{ end }} - - {{ partial "page-header.html" . }} - -
-
-
- {{ .Content }} -
-
-
- -
-{{ end }} -``` - -By default, Quire has a number of pre-defined page types like `"essay"`, `"entry"`, and `"cover"`. To create a new page type, you would follow the model of the `"essay"` page type above, and create a directory with the name of the type and in that, have a file called `single.html` with the {{< q-def "template" >}}. - -Whether in the {{< q-def "theme" >}} or in your project directory, all shortcodes go in the `layouts` directory and `shortcodes` sub-directory. The name of the shortcode file corresponds to the way the shortcode is called in the {{< q-def "Markdown" >}} files. So `q-figure.html` is the shortcode `{{}}`. - -And if you make a mistake or change your mind later, you can simply delete the copy of the file and Quire will go back to using the original template as provided in the theme. This method can also be used to add completely new templates and even new shortcodes. +TK diff --git a/content/docs-v1/zooming-images.md b/content/docs-v1/zooming-images.md index 170d8ffb..c8d7fcea 100644 --- a/content/docs-v1/zooming-images.md +++ b/content/docs-v1/zooming-images.md @@ -3,240 +3,44 @@ title: Zooming Images with IIIF weight: 6220 type: essay abstract: "Adding high-resolution zooming images to your project" -menu: false -toc: false aliases: - /documentation/zooming-images/ --- -To add high-resolution zooming images to your project, Quire uses the [International Image Interoperability Framework (IIIF)](https://iiif.io/). Within your Quire project, you can either point to existing IIIF assets or create your own. IIIF zooming images can be displayed within your Markdown pages using the `q-figure-zoom` shortcode or the built-in image viewer on entry pages. (Learn more about entry pages in the [*Collection Catalogues*](/docs-v1/collection-catalogues) section of this documentation.) +TK ## What is IIIF? -IIIF (referred to when speaking as "Triple I F") stands for the International Image Interoperability Framework. It is a shared, open set of standards for storing images and image data that allows for seamless and regularized sharing and display of those images across different uses within an institution or across different institutions. While IIIF images offer a wide variety of features and applications, Quire uses them specifically for deep zooming. - -{{< q-figure-zoom id="irises" >}} - -You can either point Quire to an existing IIIF repository of images or add high-resolution images into a Quire project directly. When adding your own images, Quire processes them into hundreds of individual image tiles. Each tile comprises a portion of the image at a particular zoom level to then be displayed in our existing zooming image viewer. Because the images have been tiled, users of your Quire project only need their browsers to load the tiles of the image portion and zoom level they're looking at at the moment. This means much faster page loads and higher-resolution images. - -{{}} - -{{< q-class "box tip" >}} -- For a deep dive into IIIF and its implementation in museums read [*Getty Common Image Service: Research & Design Report*](/downloads/gcis_r+d_report-2019.pdf/). -{{< /q-class >}} +TK ## Use Existing IIIF Images -To include existing IIIF images in your project, you will need the URL for the `info.json` file for that image, as well as a static fallback version of the image (typically a JPG) for use in Quire’s PDF and e-book outputs. - -The `info.json` file is a {{< q-def "JSON" >}}-formatted collection of useful information a file. It is [a required component of all IIIF images](https://iiif.io/api/image/3.0/#5-image-information) and includes basic object data about the full image and the availability of image tiles at different zoom levels. - -If you are working with your own institution’s IIIF repository, your digital department will be able to help you identify the `info.json` URLs you need. - -If you are working with other, open IIIF repositories, more often than not, you will find a URL to the IIIF `manifest.json` file rather than an `info.json` file. For instance, the Art Institute of Chicago has the [IIIF Manifest URL available in plain text](https://www.artic.edu/artworks/14586/the-poet-s-garden#h-iiif-manifest) on every page of its collection where IIIF is available. The Getty Museum instead includes [a IIIF logo on the artwork page](https://www.getty.edu/art/collection/objects/826/vincent-van-gogh-irises-dutch-1889/#iiif_logo), from which you can extract the `manifest.json` URL which appears at the end of the URL when you click. - -The `manifest.json` file is a more fullsome IIIF document that includes much more information about the image and the resources available. Within that `manifest.json` file however, you can look under `sequences[0].canvases[0].images[0].resource.service.@id`. The URL in the `@id` field, when appended with `/info.json`, will be what you need to add the image to your Quire project. - -In this example `manifest.json` file, the URL in the last `@id` field is what we’re looking for. - -```json -{ - "@context": "http://iiif.io/api/presentation/2/context.json", - "@id": "https://data.getty.edu/museum/api/iiif/826/manifest.json", - "@type": "sc:Manifest", - "label": "Irises (1889), Vincent van Gogh (Dutch, 1853 - 1890)", - "sequences": [ - { - "@id": "https://data.getty.edu/museum/api/iiif/826/sequence/main", - "@type": "sc:Sequence", - "canvases": [ - { - "@id": "https://data.getty.edu/museum/api/iiif/826/canvas/main", - "@type": "sc:Canvas", - "width": 9073, - "height": 7134, - "images": [ - { - "@id": "https://data.getty.edu/museum/api/iiif/826/annotation/main-image", - "@type": "oa:Annotation", - "motivation": "sc:painting", - "resource": { - "@id": "https://data.getty.edu/museum/api/iiif/671108/full/full/0/default.jpg", - "@type": "dctypes:Image", - "format": "image/jpeg", - "service": { - "@context": "http://iiif.io/api/image/2/context.json", - "@id": "https://data.getty.edu/museum/api/iiif/671108", - "profile": "http://iiif.io/api/image/2/profiles/level0.json" - }, - "width": 9073, - "height": 7134 - } - } - ] - } - ] - } - ] -} -``` - -Test it by pasting it into a browser, adding `/info.json`, and hitting enter. If correct, you’ll get [a complete JSON document](https://data.getty.edu/museum/api/iiif/671108/info.json) that includes: - -```json -"@context":"http://iiif.io/api/image/2/context.json" -"@type":"iiif:Image" -``` - -Once you’ve identified the URL to the proper `info.json` file, you can jump to the section below on [displaying IIIF image in your project](#displaying-iiif-images-in-your-project). - -{{< q-class "box warning" >}} - -- When using external resources, IIIF or otherwise, be aware that changes made to those resources by their hosts can affect the way they display in your project. Always link to reliable, permanent sources, and have a regular maintenance schedule to check for unforeseen changes that may occur after publication. - -{{< /q-class >}} +TK ## Create Your Own IIIF Images -You can create your own deep-zooming IIIF images directly within Quire. But there are a couple things you should know from the outset: - -1. **Processing IIIF image tiles is a labor intensive process.** It is highly dependent on the processing power of the computer you’re working on. We’ve found that processing a single 130MB image on an average to good machine can take upwards of 20 minutes or more. Three 6–7MB images may take only two or three minutes. Dedicate time to IIIF processing in batches when you’re not running other software on your computer. -2. **You may need to setup an additional hosting service for IIIF image files, outside your main project files.** Though small in individual file size, the sheer quantity of files (hundreds and sometimes thousands) that are associated with deep-zooming images can cause preview and build issues within your Quire project. If you have more than around 12 IIIF images you’ll want to [host them outside your project](#3-host-the-iiif-image-tiles). +TK ### 1. Prepare High-Resolution Source Images -Because the IIIF image tiles are ultimately saved as JPEGs, **we recommend starting with uncompressed, full-quality JPEG (jpg) or JPEG 2000 (jp2/jpf/jpx) files for IIIF processing**. TIFs can also work, but are typically much larger file sizes and don’t necessarily provide better end results. Quire can also process SVG and PNG files. - -Use the table below to size your source images prior to IIIF processing. Images that deviate from the recommended size guidelines for source images can also end up with misalignments and glitches at some zoom levels. The longest pixel dimension should be divisible by the 256px tile size, and be as close as possible to the final tiled image size without being equal to that size. - -{{< q-class "box tip" >}} - -- Save some time! Images larger than the recommended size for a zoom level will work but will be downsized to the final image size regardless and will cause the image processing to take longer due to the excess file size. - -{{< /q-class >}} - -| Desired Zoom Levels | Final Size of Tiled Image on Longest Side | Recommended Size of Source Image on Longest Side | -| ---------------------- | -------------- | -------------- | -| 4 | 2,048px | 2,304px | -| 5 | 4,096px | 4,352px | -| 6 | 8,192px | 8,448px | -| 7* | 16,384px | 16,640px | -| 8* | 32,768px | 33,024px | - -\* *Currently, Quire is currently set to do a maximum of 6 levels of image tiling. This can be expanded but requires a code change to both the Quire CLI and the JavaScript of your project’s theme.* - -For images smaller than 2,304px on the longest side, we recommend including them as regular non-IIIIF images. Typically, a JPEG of around 1,800px on the longest side, and at 70–80% quality, will provide both a decent web experience and work for printing in the PDF, without being too large of a file size. Read more in the [*Figure Images*](/docs-v1/figure-images/) chapter of the documentation. +TK ### 2. Process Images Into IIIF Tiles -Once they’ve been properly sized following the guidelines above, high-resolution source images should be placed in the `static/img/iiif/` directory of your project. The folder can be created if it doesn’t already exist in your project. It’s best to start with only 2–3 images to test how your computer will handle the processing. - -In your command-line shell, run the following command: - -``` -quire process --iiif -``` - -Quire will then start to process the high-resolution images into IIIF image tiles. It will output warnings if it encounters any files it can’t process, as well as messaging for when each image is completed. Quire will process all images in the `static/img/iiif/` directory, including ones that have been previously processed. So, once a batch of high-resolution files are processed, it’s best to remove them from the directory to prevent duplicate processing. - -The processed IIIF files will be placed in a `static/img/iiif/processed` directory with folder names matching the original filenames of the high-resolution images. Each folder includes the hundreds or sometimes thousands of individual image tiles arranged in their own directories that make up the zoomable image. The directory will also include an `info.json` file, which includes basic information about the full image and the availability of image tiles at different zoom levels. - -You will need the path to the `info.json` file to include it in your `figures.yaml` file when getting ready to display your IIIF images in your project. The paths are also based on the filename of the original high-resolution you processed. For example, if your high-resolution image was `00094701.jpg`, the path to the `info.json` would be `/img/iiif/processed/00094701/info.json`. +TK ### 3. Host the IIIF Image Tiles -IIIF image tiles can be hosted statically (meaning you don’t need a special server setup), just like the website edition of your Quire project. In fact, a modest number of IIIF images (around a dozen or so) can even be hosted within the project itself. In these cases, the IIIF files you’ve processed with the `quire process --iiif` command can be left where they are. It is also fine to move the processed IIIF image folders into different locations within your `static` directory. You will just need to update the paths to their `info.json` files accordingly when you’re adding them to your `figures.yaml` file, as explained in the next section. - -With more than twelve or so IIIF images, you’re going to need to host them elsewhere and then point to them from your project. This is because, though small in individual file size, the sheer quantity of files (hundreds and sometimes thousands) that are associated with deep-zooming images can cause issues when trying to run `quire preview` or use GitHub or a related service to host your project code. - -{{< q-class "box tip" >}} - -- When quantifying IIIF images, it’s hard to say how many IIIF images will be too many for a system to handle, because the number of individual files associated with a given IIIF image is highly variable. - - **For example:** - - 4 levels of zoom ≈ 100 image tiles
- 5 levels of zoom ≈ 329 image tiles
- 6 levels of zoom ≈ 1,170 image tiles - -{{< /q-class >}} - -For hosting the image tiles, if you have institutional support, your digital department should be able to provide a solution. If you’re on your own, there are any number of options. You might check out [Amazon S3](https://aws.amazon.com/s3/), which is very performant and self-serve but requires some technical savvy to get set up, or an independent hosting service like [Reclaim Hosting](https://reclaimhosting.com/shared-hosting/), which caters to the academic sector. +TK ## Display IIIF Images in Your Project -To display a IIIF image in your project, you need to point to a IIIF `info.json` file for the image. Either one you’ve identified from an [external source](#use-existing-iiif-images), or one you’ve [created yourself](#creating-your-own-iiif-images) with `quire process --iiif`. If it is an image you processed yourself and it is still in the `processed/` directory, the path to the JSON file would be `/img/iiif/processed/FILENAME/info.json`. - -Along with the path to the `info.json` file, you also need to include `media_type: "iiif"` and a path to a [lower-res static fallback version](#include-a-static-fallback-image) of the image, hosted in your project’s `static/img` directory (which is used for Quire’s PDF and e-book outputs). All of this goes in your `figures.yaml` file. - -```yaml -- id: "irises" - src: "figures/irises.jpg" - media_type: "iiif" - iiif: "https://data.getty.edu/museum/api/iiif/671108/info.json" -``` - -The image can then be added to your Markdown files using the `q-figure-zoom` shortcode, as shown below. This will display the static image on the page, and then when clicked, will open the figure viewer for the fully zoomable IIIF version. (See the page on [*Figure Images*](/docs-v1/figure-images/) for more information on the `figures.yaml` file and other figure shortcodes.) - -```go -{{}} -``` - -IIIF Images can also be displayed in the built-in image viewer on [entry pages](/docs-v1/pages). Do this by including the appropriate `id` in the [object data](/docs-v1/collection-catalogues/#capture-object-data) in your `objects.yaml` file. - -```yaml -object_list: - - id: 1 - title: *Irises* - artist: Vincent van Gogh - year: 1889 - medium: Oil on canvas - dimensions: 74.3 × 94.3 cm (29 1/4 × 37 1/8 in.) - location: J. Paul Getty Museum - link: https://www.getty.edu/art/collection/objects/826/vincent-van-gogh-irises-dutch-1889/ - figure: - - id: "irises" -``` +TK ### Include a Static Fallback Image -The static fallback image is required for displaying a version of the IIIF image outside of the zooming image viewer on the online version of your project, as well as for Quire’s PDF and e-book outputs. This is the standard `src` attribute in your `figures.yaml` listing. - -```yaml -src: "figures/irises.jpg" -``` - -Like with other non-zooming figure images, these static images for IIIF would typically be a JPEG of around 1,800px on the longest side and 70–80% quality. These specs provide both a decent web experience and work for printing in the PDF without being too large of a file size. Read more in the [*Figure Images*](/docs-v1/figure-images/) chapter of the documentation. +TK ### Set the Zoom Level -Quire will, by default, show six levels of zoom. If the IIIF image you are pointing to has less than that, you can set the number of levels in `figures.yaml` with the `zoom_max` property. This will ensure your users can’t zoom further in than the image is sized for, which would result in blurred images. - -```yaml -- id: "irises" - src: "figures/irises.jpg" - media_type: "iiif" - iiif: "/img/iiif/processed/07138601/info.json" - zoom_max: 4 -``` - -The number of zoom levels will be determined by the [size of the source file](#create-your-own-iiif-images), but you can also tell by looking a the processed image in the `static/img/iiif/processed/` directory. The number of directories there that start with “0,0,” will be equal to the number of zoom levels. In the following example, image `07138601` has four levels of zoom. - -```text -static - img - iiif - processed - 07138601 - 0,0,256,256 - 0,0,512,512 - 0,0,1024,1024 - 0,0,2048,1919 - 0,256,256,256 - 0,512,256,256 - 0,512,512,512 - 0,768,256,256 - ... -``` - -Currently, six levels of zoom is the maximum Quire is set to display. This can be expanded within your individual project, but requires a code change to both the Quire CLI and the JavaScript of your project’s theme. +TK From 45002961d6f7f0980b0be514d2e0db725cddada0 Mon Sep 17 00:00:00 2001 From: Erin Cecele Dunigan Date: Wed, 31 May 2023 13:03:20 -0700 Subject: [PATCH 2/5] replace content with TK - hidden page --- content/docs-v1/netlify.md | 118 ++--------------------------------- content/docs-v1/variables.md | 72 +-------------------- 2 files changed, 7 insertions(+), 183 deletions(-) diff --git a/content/docs-v1/netlify.md b/content/docs-v1/netlify.md index 563ffb5b..9c9e2367 100644 --- a/content/docs-v1/netlify.md +++ b/content/docs-v1/netlify.md @@ -9,128 +9,20 @@ aliases: ## Connecting Domains to Netlify -There 3 ways of connecting a domain to Netlify - -- Purchase your domain through Netlify and run your DNS through their interface -- Add a proxy to your webserver -- Add an alias CNAME to your DNS to point to your Netlify domain - -Any of these will work, it is more specific to what you want your domain to be. +TK ## Netlify Build Configuration -Instead of providing a `Production` directory or `Build` directory, you can create a `netlify.toml` file which will run commands from the root directory. These commands are set in the scripts block in the your `package.json` file. In Quire the path is `quire/themes/default/package.json`. Quire comes with a Netlify build command already, but as you will read below it is very easy to add or modify your own. - -```json -"scripts": { - "build:netlify": "webpack --config webpack/webpack.config.prod.js && cd ../../ && hugo --minify --config config.yaml,config/site.yaml" -} -``` - -This is the command we are running to build the Quire site in Netlify via our configuration below and comes installed with Quire. It first runs Webpack to build our assets, CSS, JS. Then it runs the Hugo command to build the static. - -Now let's create the `netlify.toml` in the root directory. Copy and paste this text below into a new file called `netlfy.toml` and put it in the root directory of your project. - -```toml -# netlify.toml -# The prefix is the path to your package.json file in your theme -# Change the path of your theme if it is not quire/themes/default. - -# This section is the production configuration and is all you need to deploy - -[build] -# Base is the path to your themes package.json file. -base = "themes/default" -command = "npm run build:netlify" - -[context.production.environment] -HUGO_VERSION = "0.55.5" -HUGO_ENV = "production" -HUGO_ENABLEGITINFO = "true" - -# These next configurations are optional - -# This section is the pull request configuration -[context.deploy-preview] -# Base is the path to your themes package.json file. -base = "themes/default" -command = "npm run build:netlify" - -[context.deploy-preview.environment] -HUGO_VERSION = "0.55.5" - -# This section is the branch configuration -[context.branch-deploy] -# Base is the path to your themes package.json file. -base = "themes/default" -command = "npm run build:netlify" - -[context.branch-deploy.environment] -HUGO_VERSION = "0.55.5" - -# This section is the branch configuration but targets a specific branch and also runs a different command -[context.stage] -# Base is the path to your themes package.json file. -base = "themes/default" -command = "npm run build:stage" - -[context.stage.environment] -HUGO_VERSION = "0.55.5" -``` +TK ### Alter or add another command -When we run the build process on Netlify we may want to add flags to our Hugo command to make Hugo behave differently, either on a specific branch or in the preview deploy. Let's say, for example, we want to add the flag to build drafts for a branch and not for production. We have the command `npm run build:stage` above, let's use that. - -Our scripts block will now be - -```json -"scripts": { -"build": "webpack --config webpack/webpack.config.prod.js && cd ../../ && hugo --minify --config config.yaml,config/site.yaml", -"build:stage": "webpack --config webpack/webpack.config.prod.js && cd ../../ && hugo --minify -D" -} -``` - -We are able to add the `-D` or `--buildDrafts` to the Hugo command to build drafts on our stage branch in our repository but not in master which can consider live or production. - -Adding extra commands is a great way to preview code! +TK ## Private Submodules -Once you have a proper build and deploy on Netlify, you may need to have a private submodule to save content or images that you may not want to expose. - -If you have a private submodule and need to tie it together with your project, there's a few steps you'll need to follow to get it linked and working. - -If you're new to submodules, these are some useful guides: - -- https://github.blog/2016-02-01-working-with-submodules/ -- https://git-scm.com/book/en/v2/Git-Tools-Submodules - -Once you have it working locally, you'll need to push it to Netlify. - -- Go to https://www.netlify.com/support/ and fill out a ticket -- Request an SSH key for your private submodule -- Wait until they send you an SSH key -- Go to your deploy settings in your repo, on GitHub it's https://github.com/user/repo/settings/keys (swap user and repo with your account or org and the respective private submodule repo) -- Click 'Add deploy key', add name to save it as and paste your SSH key from Netlify - -Once that's all in place redeploy and you should have your private submodule linking correctly. Go back to your Netlify deploy and trigger a redeploy. +TK ## Netlify and Git LFS -If you are using [Git Large File Storage (LFS)](https://git-lfs.github.com/) to manage large files in your GitHub or GitLab repository, you will need to set two environment variables in the Netlify deploy settings for your site. - -In Netlify, go to Site Settings > Build & Deploy > Environment. Click “Edit variables”, add these two variables, and click save: - -| Key | Value | -| --- | ----- | -| GIT_LFS_ENABLED | true | -| GIT_LFS_FETCH_INCLUDE | \*.jpeg,\*.jpg,\*.png,\*.epub,\*.mobi,\*.pdf | - -Modify the list of file types for GIT_LFS_FETCH_INCLUDE depending on what files you’ve previously chosen to have managed by Git LFS when you originally set it up in your repository. If you’re not sure, check your repository’s `.gitattributes` file. - -The settings will take effect on your next site deploy. - -If they are not set, or set improperly, you will find that certain images may not show up on your site, and download files will not be available, or will download incompletely. - -*As an alternative, Netlify also offers it’s own Large Media storage option, which you can read about at [https://docs.netlify.com/large-media/overview/](https://docs.netlify.com/large-media/overview/).* +TK \ No newline at end of file diff --git a/content/docs-v1/variables.md b/content/docs-v1/variables.md index 4871259f..f1af464c 100644 --- a/content/docs-v1/variables.md +++ b/content/docs-v1/variables.md @@ -9,76 +9,8 @@ aliases: ## Defined Variables -This default theme includes a number of style variables intended to allow for relatively easy customization without having to dig into the stylesheets and CSS markup. They are explained below and can be found and changed in `/source/css/variables.scss` file. Take special note of thee `$theme` variable which can be set to "modern" or "classic", and the `$accent-color` variable which will give your publication a distinct feel in coloring all links, buttons and other navigation elements. - -| Variable Type | Variable | Expected Value | Description | -| ------------- | -------- | -------------- | ----------- | -| Primary | $accent-color | color value | The color of buttons, links and navigation elements | -| | $content-background-color | color value | Main text area background color | -| | $secondary-background-color | color value | Additional background color, only for modern version of the theme | -| | $theme | "modern", "classic" | Shifts the overall feel and typography of the publication | -| | $navbar | "normal", "accent" | Predefined options for your navbar, white or the accent color | -| Page typography | $quire-base-font-size | unit value | 16px default | -| | $quire-page-paragraph-style | "line-space", "indent" | Paragraph display styles, either a line space and no indent, or an indent and no line space | -| Cover typography | $quire-cover-text-color | color value | | -| | $quire-cover-text-scale | integer | Use decimal numbers such as .8 or 1.3 to shift the text larger or smaller | -| Menu colors | $quire-menu-color | color value | | -| | $quire-menu-text-color | color value | | -| Image viewer colors (pop-up figure viewer & entry page viewer) | $quire-entry-image-color | color value | The background of the image viewer on entry pages | -| | $quire-entry-image-icons-color | color value | | -| Highlight color | $quire-hover-color | color value | Used on active links and when hovering over table rows | -| Print/PDF output | $print-width | unit value | 8.5in default| -| | $print-height | unit value | 11in default | -| | $print-bleed | unit value | .125in default | -| | $print-base-font-size | unit value | 8.5pt default | -| | $print-text-color | color value | Specifying a plain black will avoid excessive color printing costs | -| | $print-splash-color | color value | Background color for full-bleed splash pages | -| | $print-entry-image-color | color value | Background color for full-bleed image pages | -| | $print-entry-image-display | "all", "first" | Output "all" the images associated with an object on an entry page, or only the "first", main image | -| Fonts | $quire-primary-font | font name | This theme includes three embedded, open license fonts, (Noto Sans, Noto Serif, and IBM Plex Sans Condensed) and also uses the widely available Times. While other fonts can be specified for use, do so with caution and line spacing, element width and margin can all shift from font to font. | -| | $quire-headings-font | font name | See above | -| | $quire-footnotes-font | font name | See above | -| | $quire-navigation-font | font name | See above | -| Navbar | $quire-navbar-color | color value | | -| | $quire-navbar-hover-color | color value | | -| | $quire-navbar-text-color | color value | | -| Cover colors | $quire-cover-color-1 | color value | The cover includes a gradient of two colors, specified here, and a white/transparent wave graphic specified in the cover.md of the content files | -| | $quire-cover-color-2 | color value | | -| Layout sizes | $quire-menu-width | unit value | 352px default | -| | $navbar-height | unit value | 3rem default | -| | $quire-entry-header-height | unit value | 6rem default, determines the relative height of the entry page image viewer when in horizontal viewing mode | -| | $quire-map-height | unit value | 500px default | -| | $quire-deepzoom-height | unit value | 500px default | - -## Special Classes - -| Class | Description | -| ----- | ----------- | -| page-one | For PDF output, should be used on the page/chapter where you want page 1 to start, `class: page-one`, often an Introduction or first essay rather than the Contents pages or other frontmatter | -| backmatter | Can be applied to Markdown text with the `q-class` shortcode and text will be styled smaller, like the default footnotes style -| is-pulled-left, is-pulled-right | Can be applied to figures or figure groups with their shortcodes, will make figures roughly half-column width and will float them to the left or right of the text | -| brief, list, abstract, grid | Can be applied to pages with a `type: contents`, will alter how the contents are displayed | -| side-by-side, landscape | Can be applied to pages with a `type: entry`, will alter how the image viewer is displayed | +TK ## Configuration Parameters -Outside of the theme files themselves, a Quire project will also have a config.yaml file which includes a number of parameters the theme relies on. - -| Parameter | Expected Value | Description | -| --------- | -------------- | ----------- | -| runTests | boolean | Turn on or off the built-in tests that check for certain common errors and post error messages in the CLI output. | -| searchEnabled | boolean | Turn on or off the built-in text search capability for users | -| licenseIcons | boolean | Whether or not to display Creative Commons license icons | -| pageLabelDivider | string | ". " default, etermines the text/spacing to be inserted between page .label and page .title | -| citationPageLocationDivider | string | ", " default, determines the text/spacing to be inserted between the citation and the page number in the q-cite shortcode | -| displayBiblioShort| boolean | Whether a bibilography generated with the q-cite or q-bibliography shorcodes should display the short form of the reference, along with the long. | -| imageDir | string | "img" default, the directory in the `/static/` directory where you put your images | -| `menuClass` | "brief", "list" | "list" is the default, "brief" will show only top-level pages and sections, no sub-sections. | -| prevPageButtonText | string | "Back" default | -| nextPageButtonText | string | "Next" default | -| entryPageSideBySideLayout | boolean | Entry pages can have a side-by-side layout with image on the left and text on the right, this can be controlled by `class: side-by-side` in the page YAML, or globally with this parameter | -| entryPageObjectLinkText | string | "View in Collection" default | -| figureLabelLocation | "on-top", "below" | Whether the figure label is "on-top" of the image in the upper left corner, or "below" it with the caption | -| figureModal | boolean | If figures should be clickable to open into a full-screen modal window | -| figureModalIcons | boolean | Whether to display icons with the figure modal links | -| figureZoom | boolean | Whether figures should zoom or not inside the modal | +TK From 7d9cd6c0b723ba49e58a157aa20863fba707c96d Mon Sep 17 00:00:00 2001 From: Erin Cecele Dunigan Date: Wed, 31 May 2023 13:04:26 -0700 Subject: [PATCH 3/5] rename GitHub article - hidden page --- content/resources/github-article.md | 101 ++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 content/resources/github-article.md diff --git a/content/resources/github-article.md b/content/resources/github-article.md new file mode 100644 index 00000000..4946bfdb --- /dev/null +++ b/content/resources/github-article.md @@ -0,0 +1,101 @@ +--- +title: Learning GitHub +weight: 7550 +type: page +online: false +--- + +## Steps for Using Quire and GitHub Together + +The following steps are examples of a potential workflow when using GitHub as a project management tool alongside Quire. Creating branches and making pull requests are an optional way of working that provides extra checks and balances. You can learn more about GitHub in the [*Project Management for GitHub*](/docs-v1/github) section of our documentation. + +### Host Your Quire Project on Github +*The most common way to get started with GitHub is to upload or host your project on the platform.* + +1. Open GitHub Desktop and click the upper left-hand corner where it says “Current Repository.” Click “Add” and choose the option to “Add Existing repository…” +2. Navigate to your `[quire-project-name]` folder and click “Add Repository.” +3. If there are any items listed in the window’s left-hand pane, you will need to commit them to your project. As this will be your first commit, type “Initial commit” in the Summary field. +4. Click the “Commit to master” button. + +### Download Your Quire Project from Github +*If a colleague has already hosted your project on GitHub, you will need to be added as a project collaborator, and then you can download or clone the project to your computer and work on it locally.* + +1. Open GitHub Desktop. +2. Click on the upper left-hand corner of the application window, where it says “Current Repository”. Click “Add” and choose the option to “Clone repository…” +3. Click the URL menu option and cut-and-paste the URL for your desired repository. (Alternately, you can copy this project directly from GitHub.com. Navigate to the project on GitHub, click the green “Code” button, select “Open with GitHub Desktop”, and follow the prompts.) +4. Save the Quire project. (We recommend saying it in your home directory.) + +### Preview Your Quire Publication +*This is recommended as a way to double-check the edits you are making in your Quire publication.* + +1. Next, you are going to use the command line to navigate through your computer files. +- If using a Mac computer, press Command-Spacebar to open Spotlight. Then write “Terminal” and hit enter. +- For PCs, we recommend installing Git for Windows, which comes with a shell called Git BASH. +2. Use the cd command to navigate to your computer's home directory and then navigate into your `[quire-project-name]` folder. (For more on using command line see our [*Learning Command Line*](/resources/command-line) article.) +3. Once you are in your `[quire-project-name]` folder, run the following commands: +``` +quire install +quire preview +``` +4. Go to [http://localhost:8080](http://localhost:8080) to view the changes live. + +### Open Your Project in GitHub Desktop +*You will use GitHub to save, manage, and track any changes made to your Quire project.* + +1. At the top right, click "Current Repository" and either choose your project repository from the list or add it per the instructions in [Download Your Quire Project from GitHub](#download-your-quire-project-from-github). + +### Create a New Branch in GitHub Desktop +*A branch is a parallel version of your project that you can edit in directly without compromising the main version.* + +1. Before starting a new branch, click the “Fetch Origin” button at the top right. This will pull down any recently merged changes to the master project. That way when you start a new branch you are working off the most up-to-date version. +2. Navigate to where it says “Current Branch” at the top of your GitHub Desktop window. +3. Click the drop-down arrow and select “new branch” to the right of the Filter box. +4. Name your branch. +5. Select “main” where it says “Create branch based on.” This means you are creating a new branch that runs parallel to the main project. + +### Open Project File in Atom +*When you are ready to start editing, open your Quire project in your text editor to get started. While we recommend using Atom you are welcome to use any text editor that you feel comfortable with.* + +1. Open Atom +2. Click File > Open +3. Navigate to your home directory and your GitHub folder +4. Select `[quire-project-name]` +5. In Atom, expand the contents folder to see the editable markdown files + +### Save Changes in Atom +*After you make changes in Atom, be sure to save them!* + +1. To save, hit File > Save or Command-S (Mac) or Control-S (PC). +2. If working on multiple markdown files, make sure to save each file individually. You will see a little blue dot at the top of the page if there are any unsaved changes. + +### Make Commits in GitHub Desktop +*A commit is a record of a change or revision you have made to your Quire project. It is one step in the process of saving your changes to the git record of your project.* + +1. At the bottom left, above where it says description, write a short name for your commit. You have the option to include a description as well. +2. Press the blue button that says “Commit to [branch name].” + +### Push Changes in GitHub +*You must “push” the changes to GitHub to save them to your repository.* + +1. After you have made all your commits, click on the “Push Origin” button at the top right. +2. Now the changes to your project have been successfully saved to your branch on GitHub. + +### Create a Pull Request in GitHub +*Once you are done making changes, you can submit a “pull request," a request for a collaborator to review or comment on your work.* + +1. Click the blue-button that says “Create Pull Request.” This will take you to GitHub.com. +2. Confirm that the branch in the base drop-down menu is the branch where you want to merge your changes. In most cases, this will be the master or main branch. +3. You can leave the default title or type a new title and description for your pull request. +4. On the right-hand side, you will see an option to choose a reviewer. Choose the colleague you would like to review your work. (Note" reviewers must be added as collaborators first.) +5. Click the green-button that says “Create Pull Request” if all your changes are ready for review. Or click the drop-down arrow and choose “Create Draft Pull Request” if you are still making changes that will be included in this particular pull request. + +### Review and Merge a Pull Request in GitHub +*Comment on and request changes to a pull request. Once the pull request is approved changes can be merged into the master copy of your project.* + +1. Navigate to “Pull Requests” on the main page of your repository. +2. In the list of pull requests, choose the one you’d like to review. +3. Click “+/- Files changed”. +4. Hover over the section of text you would like to comment on. +5. You will see a blue square with a plus mark pop-up. Write your comments here. +6. When you are done commenting click, “Start a Review.” You will have the option to comment, approve, and request changes. +7. Once the pull request has been approved, provided there are no conflicts, you will see a green-button that says “merge pull request.” Click this and, voila, your changes are now incorporated. From d7d08a1fea356448e1cbab045a52d63c80a17e4a Mon Sep 17 00:00:00 2001 From: Erin Cecele Dunigan Date: Wed, 31 May 2023 13:04:47 -0700 Subject: [PATCH 4/5] Move GitHub from docs to resources --- content/docs-v1/github.md | 186 ----------------------------- content/resources/github.md | 229 ++++++++++++++++++++++++------------ 2 files changed, 157 insertions(+), 258 deletions(-) delete mode 100644 content/docs-v1/github.md diff --git a/content/docs-v1/github.md b/content/docs-v1/github.md deleted file mode 100644 index 5ac58cda..00000000 --- a/content/docs-v1/github.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: Project Management with GitHub -weight: 6100 -type: essay -abstract: Use GitHub to host your project, track changes, and collaborate -aliases: - - /documentation/github/ ---- - -[GitHub](https://github.com) is a project management platform centered around git-based version control. While it was originally developed as a useful tool for developers, it is now used by artists, writers, and other non-tech professionals. In fact, Getty uses GitHub to manage all of its publications, as well as Quire itself. We strongly recommend using GitHub as a tool for managing your Quire projects (whether collaborating or working solo). - -**Here are some of GitHub's main advantages:** - -- GitHub is [free to use](https://github.com/pricing). -- It's a secure platform for hosting your project's code and creating an electronic backup of your work. -- GitHub saves the entire version history of your project (including deleted files), enabling you to track changes, revert changes, and restore earlier versions. -- You can use GitHub to create test versions of your project and experiment with new ideas before officially incorporating them. -- Github makes working with collaborators easy. You and your colleagues can work in different versions of the project, review and comment on one another's work, and consolidate any approved changes into the master project. -- In the case of Quire, we also use GitHub to host our [community forum](https://github.com/thegetty/quire/discussions) where you can ask and answer questions, share ideas, and assist fellow Quire community members. - -{{< q-class "box tip" >}} -- For more information, we recommend checking out [GitHub Docs](https://docs.github.com/en/free-pro-team@latest/github) to learn by topic, [GitHub Glossary](https://docs.github.com/en/github/getting-started-with-github/github-glossary) to understand key terms, and [GitHub Guides](https://guides.github.com/) for a broad overview. We also encourage you to check out Coding Train's [Git and Github for Poets](https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV) video series as a helpful primer. -{{< /q-class >}} - -**To get started**: - -1. Sign up for a free [GitHub account](https://github.com/join) -2. Download and install [GitHub Desktop](https://desktop.github.com/), unless you’re familiar with using git from the command-line -3. Download and install [Git LFS (Large File Storage)](https://docs.github.com/en/github/managing-large-files/installing-git-large-file-storage). Learn more in the [Manage Large File Sizes with Git LFS](/#manage-large-file-sizes-with-git-lfs/) section below. - -**Next, you will have two options**: - -1. [**Host Your Project's Code on GitHub**](#host-your-projects-code-on-github): Create a new repository on GitHub and add a project that lives locally on your computer. (This would be the case if you recently used `quire new`.) Please note, you are only hosting your project's code and not the actual online version of it. -2. [**Clone an Existing Project from Github**](#clone-an-existing-project-from-github): Copy an existing repository off GitHub to work locally on your computer. This would be the case when collaborating with others who have already created a repository. - -## Host Your Project's Code on GitHub - -GitHub uses something called "git" to track changes in project files. When you start a Quire project with `quire new`, it comes already configured as a git repository. (You might have noticed a mysterious `.git` directory in your folder.) This means your project is ready to be uploaded to GitHub as a new [repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-repositories). - -1. Open GitHub Desktop and click the upper left-hand corner where it says "Current Repository." Click "Add" and choose the option to "Add Existing repository..." - -2. Navigate to the project in your {{< q-def "home directory" >}} and click "Add Repository." - -3. If there are any items listed in the window's left-hand pane, you will need to commit them to your project. As this will be your first commit, type "Initial commit" in the Summary field and click the "Commit to master" button. - -{{< q-figure id="github-desktop-initial-commit" >}} - -4. Click the blue button that says "Publish Repository." This will push your repository up to GitHub.com. In the pop-window, keep the name as is and add a description if you would like. Then click "Publish Repository." - -{{< q-figure id="github-desktop-publish" >}} - -Your project code is now on GitHub! To see it, go to Repository > View on GitHub or visit https://github.com/YOUR-USERNAME/YOUR-PROJECT-NAME. - -## Clone an Existing Project from GitHub - -If you are collaborating on a project, and one of your colleagues has already hosted your project code on GitHub, you can clone (or make a copy) of this repository to work on locally. - -1. Click on the upper left-hand corner of GitHub Desktop where it says "Current Repository." Click "Add" and choose the option to "Clone repository..." - -2. Click the URL menu option and cut and paste the URL for your desired repository. Be sure to choose the local path where you want your project to live on your computer. We recommend creating a GitHub folder in your home directory and storing the project in there. (Alternately, you can copy this project directly from GitHub.com. Navigate to the project on GitHub, click the green “Code” button, select “Open with GitHub Desktop,” and follow the prompts.) - -3. You now have a copy of that project on your computer connected to the original code on GitHub. Before you can collaborate, you will need to either add your colleagues as collaborators or host your project in an organizational GitHub account where everyone is a member. Learn more in the [*Collaborate with Others Using GitHub*](/#collaborate-with-others-using-GitHub/) section below. - -{{< q-class "box warning" >}} -- To view a preview of a Quire project cloned from GitHub, you’ll need to first run the `npm install` command in your command-line shell. Then run `quire preview` and navigate to [http://localhost:1313/](http://localhost:1313/). -{{< /q-class >}} - -{{< q-class "box tip" >}} -- Learn how to take an existing Quire project in GitHub and use it as the basis for a new one in our [*Use an Existing Quire Project as a Template*](/docs-v1/serial-publications/) section. This is especially useful for serial publications such as journals. -{{< /q-class >}} - -## Manage Project Changes on GitHub - -There are three basic steps for making and managing changes to your project on GitHub: - -1. Save changes in your text editor -2. Commit those changes to the git repository -3. Push those commits up to GitHub - -### Save Changes - -Open your project in your text editor (File > Open > [your project name]), make, and save changes. When you go into GitHub Desktop, you should see a list of all the files added, deleted, or edited in the left-hand pane. On the right, you'll see exactly what changes were made inside each file. Old text will be highlighted in red, while any new text will be highlighted in green. This enables you to compare and review changes. - -{{< q-class "box tip" >}} -- Save changes with File > Save (or Command-S on Macs and Control-S on PCs). If working on multiple markdown files, make sure to save each file individually. You will see a little blue dot at the top of the page if there are any unsaved changes. -{{< /q-class >}} - -### Commit Changes - -At this point, your changes have been saved locally (i.e. on your computer), but they aren't in the git record of your project yet. For that, you need to make a [commit](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/committing-and-reviewing-changes-to-your-project#about-commits), a small grouping of meaningful changes. - -To make a commit, at the bottom left, above where it says description, write a short name summarizing the change you’re making (a longer description is optional) and click the "Commit to master" button. Keep in mind, a key advantage of GitHub is that you can undo your work by reverting commits and returning to earlier versions of your project. Here are a few tips for styling your commits to make that process easier: - -- Keep the commit name concise (around 50 characters max), so you can quickly and easily browse them in the future. -- If you need to explain the commit in greater detail, use the description field (around 72 characters max). -- The summary should be a phrase that completes the sentence “This commit will __.” -- Use present/imperative tense, such as “Add contributor names and bios;” “Fix typos in section pages;” or “Change header color.” - -When naming commits, think of them as purposefully connected bundles that you could undo at a later date without affecting other areas of your project. Rather than committing all the random changes you made to a single file or everything you did before lunch that day, make small and frequent commits. And remember to commit changes that *make sense together*. - -{{< q-class "box tip" >}} -- Changes are organized by the file in which they were made. Keep this in mind if making multiple types of changes to one file. Use the checkboxes at the lefthand side of your GitHub Desktop window to select which changes will or won’t be included in a given commit. Break your work into individual commits or commits with multiple changes. -{{< /q-class >}} - -### Push Changes - -Even after saving changes in your text editor and committing them in GitHub Desktop, GitHub still doesn’t know about them. For that, you need to [push](hhttps://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/pushing-changes-to-github#pushing-changes-to-github) your commits to GitHub. - -Click on the "Push origin" link in the upper-right corner. (If you haven't committed changes yet, this area will say "Fetch Origin" instead). Pushing can include one or many commits, and you can push as often as you’d like. It’s typically good to do it at least a couple of times a day when actively working on a project. - -Now the changes to your project have been successfully saved in GitHub! - -## Collaborate with Others Using GitHub - -One of the main advantages of using GitHub is that it's an excellent tool for managing projects with multiple people working on them. Once the project is on GitHub and cloned by you and your colleagues, you can all make changes and commits to the same project. - -When setting-up a new repository you have [two options](https://docs.github.com/en/github/getting-started-with-github/types-of-github-accounts): you can invite users to become collaborators to your *personal repository* or groups of people can collaborate across many projects simultaneously with *organization accounts*. Each has different options for [managing settings and permissions](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-user-account-settings). - -Clear communication is vital when collaborating with GitHub. If multiple people are working on a project and all are making changes to the same files, there’s a good chance you will run into conflicts. While git is specifically designed to deal with these sorts of issues, it's important to avoid working on the same sections at the same time. - -### Create a Branch - -A good way to manage users' changes and avoid conflicts is by using [branches](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/managing-branches). Branches are essentially parallel versions of a project. Users can make changes on their branch without affecting the main version of the project. This allows you to review changes and identify possible conflicts before they are incorporated into your project. - -1. Before starting a new branch, click the “Fetch Origin" button at the top right. This will pull down any recently merged changes to the master project. That way, when you start a new branch, you are working off the most up-to-date version of your project. -2. Navigate to where it says “Current Branch” at the top of your GitHub Desktop window. -3. Click the drop-down arrow and select “new branch” to the right of the Filter box. -4. Name your branch. -5. Select “main” where it says “Create branch based on.” This means you are creating a new branch that runs parallel to the main project. Every time you open the project to work on it, make sure you are working in the correct branch. - -Tips for naming branches: - -- Keep branch names concise. -- A branch name should be indicative of the work you are doing or who is working on that particular branch. -- Do not use uppercase letters. -- Separate words with dashes (GitHub won't permit spaces). - -### Submit a Pull Request - -Once you have pushed the changes on your branch, you will be prompted to submit a [pull request](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/creating-an-issue-or-pull-request#creating-a-pull-request). This is a request for your collaborators to review and comment on changes. - -1. Click the blue-button that says “Create Pull Request.” This will take you to GitHub.com. -2. Confirm that the branch in the "base" drop-down menu is where you want to merge your changes. In most cases, this will be the master or main branch. -3. You can leave the default title or create a new title and description for your pull request. -4. On the right-hand side, you will see an option to choose the reviewer(s) you would like to overlook your changes. -5. If all your changes are ready for review, click the green-button that says “Create Pull Request." Or click the drop-down arrow and choose “Create Draft Pull Request” if you are still making changes in this particular pull request. - -### Review & Merge Changes - -Now you have the opportunity to review changes, provide feedback, or request edits. Once the pull request has been approved, you can [merge](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/merging-a-pull-request#about-pull-request-merges) these changes into the master version of your project. - -1. Navigate to "Pull Requests" on the main page of your repository. -2. In the list of pull requests, choose the one you'd like to review. -3. Click "+/- Files changed". -4. Hover over the section of text you would like to comment on. -5. You will see a blue square with a plus mark pop-up. Write your comments here. -6. When you are done commenting click, "Start a Review." You will have the option to comment, approve, and request changes. -7. Once the pull request has been approved, provided there are no conflicts, you will see a green-button that says "merge pull request." Click this and, voila, your changes are now incorporated. - -{{< q-class "box tip" >}} -Merge conflicts will happen when you attempt to merge branches that have competing commits. Read more about [addressing and resolving merge conflicts](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts) in the GitHub documentation. -{{< /q-class >}} - -## Manage Third Party Assets with GitHub - -If you plan to make your repository visible to the public at some point, **you should not commit third-party licensed assets into it**, as this can expose those assets to easy, unlicensed use by other people. We recommend either keeping those assets out of the git record completely and managing them locally or adding them in as a secondary repository that always remains private but can be connected to the main repo as a [git submodule](https://github.blog/2016-02-01-working-with-submodules/). - -### Keeping Assets Out of Git - -For anything you do not want to include in git, you can add a listing for it in your project’s main `.gitignore` file (which you can see when viewing your project in your text editor). You can choose to ignore files by name or by extension, or you can ignore entire directories. - -For instance, you might add all your third-party licensed images into a `licensed` folder in your `content/_assets/images/` folder. By adding `content/_assets/images/licensed` to a new line in your `.gitignore` file, none of those files will be added to the git record and uploaded to GitHub. You’ll only have access to ignored files locally or for collaborators if you provide them copies of the files that they can manually add into their own copies of the repository. - -{{< q-class "box warning" >}} - -- Items added to your `.gitignore` file that have already been committed to your repository will no longer be tracked going forward but will still exist in your project’s history. Permanently removing files is possible, but [much more of a process](https://docs.github.com/en/github/authenticating-to-github/removing-sensitive-data-from-a-repository). - -{{< /q-class >}} - -### Keeping Assets in a Git Submodule - -Where using `.gitignore` can ensure certain sensitive or third-party files won’t get added into a project repository and thus be uploaded to GitHub, it means you have to manually track and manage those files yourself. Another option is to create a second project repository on GitHub to stay private even while your main project is made public. You include that second repository as a submodule within your main repository. - -For instance, you might add all your third-party licensed images into a `my-project-licensed-images` repository and then link that repository as a submodule into the `content/_assets/images/licensed` folder of your main project repository. In this way, Quire can still build the site and output files and preview those images as normal. The files will also be under version control with git and connected to your project (so there’s no manual syncing to do), but you’ll be able to keep them private to everyone except your team or collaborators. - -There are good directions on [working with submodules](https://github.blog/2016-02-01-working-with-submodules/) on GitHub’s blog. Note, however that managing commits to a submodule repository within a repository can be a little tricky, so it’s best not to go this route unless you are comfortable with git and GitHub already or have access to good support. diff --git a/content/resources/github.md b/content/resources/github.md index 4946bfdb..42e2c29e 100644 --- a/content/resources/github.md +++ b/content/resources/github.md @@ -1,101 +1,186 @@ --- -title: Learning GitHub -weight: 7550 -type: page -online: false +title: GitHub +weight: 7400 +type: essay +abstract: Use GitHub to host your project, track changes, and collaborate +aliases: + - /documentation/github/ --- -## Steps for Using Quire and GitHub Together +[GitHub](https://github.com) is a project management platform centered around git-based version control. While it was originally developed as a useful tool for developers, it is now used by artists, writers, and other non-tech professionals. In fact, Getty uses GitHub to manage all of its publications, as well as Quire itself. We strongly recommend using GitHub as a tool for managing your Quire projects (whether collaborating or working solo). -The following steps are examples of a potential workflow when using GitHub as a project management tool alongside Quire. Creating branches and making pull requests are an optional way of working that provides extra checks and balances. You can learn more about GitHub in the [*Project Management for GitHub*](/docs-v1/github) section of our documentation. +**Here are some of GitHub's main advantages:** -### Host Your Quire Project on Github -*The most common way to get started with GitHub is to upload or host your project on the platform.* +- GitHub is [free to use](https://github.com/pricing). +- It's a secure platform for hosting your project's code and creating an electronic backup of your work. +- GitHub saves the entire version history of your project (including deleted files), enabling you to track changes, revert changes, and restore earlier versions. +- You can use GitHub to create test versions of your project and experiment with new ideas before officially incorporating them. +- Github makes working with collaborators easy. You and your colleagues can work in different versions of the project, review and comment on one another's work, and consolidate any approved changes into the master project. +- In the case of Quire, we also use GitHub to host our [community forum](https://github.com/thegetty/quire/discussions) where you can ask and answer questions, share ideas, and assist fellow Quire community members. -1. Open GitHub Desktop and click the upper left-hand corner where it says “Current Repository.” Click “Add” and choose the option to “Add Existing repository…” -2. Navigate to your `[quire-project-name]` folder and click “Add Repository.” -3. If there are any items listed in the window’s left-hand pane, you will need to commit them to your project. As this will be your first commit, type “Initial commit” in the Summary field. -4. Click the “Commit to master” button. +{{< q-class "box tip" >}} +- For more information, we recommend checking out [GitHub Docs](https://docs.github.com/en/free-pro-team@latest/github) to learn by topic, [GitHub Glossary](https://docs.github.com/en/github/getting-started-with-github/github-glossary) to understand key terms, and [GitHub Guides](https://guides.github.com/) for a broad overview. We also encourage you to check out Coding Train's [Git and Github for Poets](https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV) video series as a helpful primer. +{{< /q-class >}} -### Download Your Quire Project from Github -*If a colleague has already hosted your project on GitHub, you will need to be added as a project collaborator, and then you can download or clone the project to your computer and work on it locally.* +**To get started**: -1. Open GitHub Desktop. -2. Click on the upper left-hand corner of the application window, where it says “Current Repository”. Click “Add” and choose the option to “Clone repository…” -3. Click the URL menu option and cut-and-paste the URL for your desired repository. (Alternately, you can copy this project directly from GitHub.com. Navigate to the project on GitHub, click the green “Code” button, select “Open with GitHub Desktop”, and follow the prompts.) -4. Save the Quire project. (We recommend saying it in your home directory.) +1. Sign up for a free [GitHub account](https://github.com/join) +2. Download and install [GitHub Desktop](https://desktop.github.com/), unless you’re familiar with using git from the command-line +3. Download and install [Git LFS (Large File Storage)](https://docs.github.com/en/github/managing-large-files/installing-git-large-file-storage). Learn more in the [Manage Large File Sizes with Git LFS](/#manage-large-file-sizes-with-git-lfs/) section below. -### Preview Your Quire Publication -*This is recommended as a way to double-check the edits you are making in your Quire publication.* +**Next, you will have two options**: -1. Next, you are going to use the command line to navigate through your computer files. -- If using a Mac computer, press Command-Spacebar to open Spotlight. Then write “Terminal” and hit enter. -- For PCs, we recommend installing Git for Windows, which comes with a shell called Git BASH. -2. Use the cd command to navigate to your computer's home directory and then navigate into your `[quire-project-name]` folder. (For more on using command line see our [*Learning Command Line*](/resources/command-line) article.) -3. Once you are in your `[quire-project-name]` folder, run the following commands: -``` -quire install -quire preview -``` -4. Go to [http://localhost:8080](http://localhost:8080) to view the changes live. +1. [**Host Your Project's Code on GitHub**](#host-your-projects-code-on-github): Create a new repository on GitHub and add a project that lives locally on your computer. (This would be the case if you recently used `quire new`.) Please note, you are only hosting your project's code and not the actual online version of it. +2. [**Clone an Existing Project from Github**](#clone-an-existing-project-from-github): Copy an existing repository off GitHub to work locally on your computer. This would be the case when collaborating with others who have already created a repository. -### Open Your Project in GitHub Desktop -*You will use GitHub to save, manage, and track any changes made to your Quire project.* +## Host Your Project's Code on GitHub -1. At the top right, click "Current Repository" and either choose your project repository from the list or add it per the instructions in [Download Your Quire Project from GitHub](#download-your-quire-project-from-github). +GitHub uses something called "git" to track changes in project files. When you start a Quire project with `quire new`, it comes already configured as a git repository. (You might have noticed a mysterious `.git` directory in your folder.) This means your project is ready to be uploaded to GitHub as a new [repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-repositories). -### Create a New Branch in GitHub Desktop -*A branch is a parallel version of your project that you can edit in directly without compromising the main version.* +1. Open GitHub Desktop and click the upper left-hand corner where it says "Current Repository." Click "Add" and choose the option to "Add Existing repository..." -1. Before starting a new branch, click the “Fetch Origin” button at the top right. This will pull down any recently merged changes to the master project. That way when you start a new branch you are working off the most up-to-date version. -2. Navigate to where it says “Current Branch” at the top of your GitHub Desktop window. -3. Click the drop-down arrow and select “new branch” to the right of the Filter box. -4. Name your branch. -5. Select “main” where it says “Create branch based on.” This means you are creating a new branch that runs parallel to the main project. +2. Navigate to the project in your {{< q-def "home directory" >}} and click "Add Repository." + +3. If there are any items listed in the window's left-hand pane, you will need to commit them to your project. As this will be your first commit, type "Initial commit" in the Summary field and click the "Commit to master" button. + +{{< q-figure id="github-desktop-initial-commit" >}} + +4. Click the blue button that says "Publish Repository." This will push your repository up to GitHub.com. In the pop-window, keep the name as is and add a description if you would like. Then click "Publish Repository." + +{{< q-figure id="github-desktop-publish" >}} + +Your project code is now on GitHub! To see it, go to Repository > View on GitHub or visit https://github.com/YOUR-USERNAME/YOUR-PROJECT-NAME. + +## Clone an Existing Project from GitHub + +If you are collaborating on a project, and one of your colleagues has already hosted your project code on GitHub, you can clone (or make a copy) of this repository to work on locally. + +1. Click on the upper left-hand corner of GitHub Desktop where it says "Current Repository." Click "Add" and choose the option to "Clone repository..." + +2. Click the URL menu option and cut and paste the URL for your desired repository. Be sure to choose the local path where you want your project to live on your computer. We recommend creating a GitHub folder in your home directory and storing the project in there. (Alternately, you can copy this project directly from GitHub.com. Navigate to the project on GitHub, click the green “Code” button, select “Open with GitHub Desktop,” and follow the prompts.) + +3. You now have a copy of that project on your computer connected to the original code on GitHub. Before you can collaborate, you will need to either add your colleagues as collaborators or host your project in an organizational GitHub account where everyone is a member. Learn more in the [*Collaborate with Others Using GitHub*](/#collaborate-with-others-using-GitHub/) section below. + +{{< q-class "box warning" >}} +- To view a preview of a Quire project cloned from GitHub, you’ll need to first run the `npm install` command in your command-line shell. Then run `quire preview` and navigate to [http://localhost:1313/](http://localhost:1313/). +{{< /q-class >}} + +{{< q-class "box tip" >}} +- Learn how to take an existing Quire project in GitHub and use it as the basis for a new one in our [*Use an Existing Quire Project as a Template*](/docs-v1/serial-publications/) section. This is especially useful for serial publications such as journals. +{{< /q-class >}} + +## Manage Project Changes on GitHub + +There are three basic steps for making and managing changes to your project on GitHub: + +1. Save changes in your text editor +2. Commit those changes to the git repository +3. Push those commits up to GitHub + +### Save Changes + +Open your project in your text editor (File > Open > [your project name]), make, and save changes. When you go into GitHub Desktop, you should see a list of all the files added, deleted, or edited in the left-hand pane. On the right, you'll see exactly what changes were made inside each file. Old text will be highlighted in red, while any new text will be highlighted in green. This enables you to compare and review changes. + +{{< q-class "box tip" >}} +- Save changes with File > Save (or Command-S on Macs and Control-S on PCs). If working on multiple markdown files, make sure to save each file individually. You will see a little blue dot at the top of the page if there are any unsaved changes. +{{< /q-class >}} + +### Commit Changes + +At this point, your changes have been saved locally (i.e. on your computer), but they aren't in the git record of your project yet. For that, you need to make a [commit](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/committing-and-reviewing-changes-to-your-project#about-commits), a small grouping of meaningful changes. + +To make a commit, at the bottom left, above where it says description, write a short name summarizing the change you’re making (a longer description is optional) and click the "Commit to master" button. Keep in mind, a key advantage of GitHub is that you can undo your work by reverting commits and returning to earlier versions of your project. Here are a few tips for styling your commits to make that process easier: + +- Keep the commit name concise (around 50 characters max), so you can quickly and easily browse them in the future. +- If you need to explain the commit in greater detail, use the description field (around 72 characters max). +- The summary should be a phrase that completes the sentence “This commit will __.” +- Use present/imperative tense, such as “Add contributor names and bios;” “Fix typos in section pages;” or “Change header color.” -### Open Project File in Atom -*When you are ready to start editing, open your Quire project in your text editor to get started. While we recommend using Atom you are welcome to use any text editor that you feel comfortable with.* +When naming commits, think of them as purposefully connected bundles that you could undo at a later date without affecting other areas of your project. Rather than committing all the random changes you made to a single file or everything you did before lunch that day, make small and frequent commits. And remember to commit changes that *make sense together*. -1. Open Atom -2. Click File > Open -3. Navigate to your home directory and your GitHub folder -4. Select `[quire-project-name]` -5. In Atom, expand the contents folder to see the editable markdown files +{{< q-class "box tip" >}} +- Changes are organized by the file in which they were made. Keep this in mind if making multiple types of changes to one file. Use the checkboxes at the lefthand side of your GitHub Desktop window to select which changes will or won’t be included in a given commit. Break your work into individual commits or commits with multiple changes. +{{< /q-class >}} -### Save Changes in Atom -*After you make changes in Atom, be sure to save them!* +### Push Changes -1. To save, hit File > Save or Command-S (Mac) or Control-S (PC). -2. If working on multiple markdown files, make sure to save each file individually. You will see a little blue dot at the top of the page if there are any unsaved changes. +Even after saving changes in your text editor and committing them in GitHub Desktop, GitHub still doesn’t know about them. For that, you need to [push](hhttps://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/pushing-changes-to-github#pushing-changes-to-github) your commits to GitHub. -### Make Commits in GitHub Desktop -*A commit is a record of a change or revision you have made to your Quire project. It is one step in the process of saving your changes to the git record of your project.* +Click on the "Push origin" link in the upper-right corner. (If you haven't committed changes yet, this area will say "Fetch Origin" instead). Pushing can include one or many commits, and you can push as often as you’d like. It’s typically good to do it at least a couple of times a day when actively working on a project. -1. At the bottom left, above where it says description, write a short name for your commit. You have the option to include a description as well. -2. Press the blue button that says “Commit to [branch name].” +Now the changes to your project have been successfully saved in GitHub! -### Push Changes in GitHub -*You must “push” the changes to GitHub to save them to your repository.* +## Collaborate with Others Using GitHub -1. After you have made all your commits, click on the “Push Origin” button at the top right. -2. Now the changes to your project have been successfully saved to your branch on GitHub. +One of the main advantages of using GitHub is that it's an excellent tool for managing projects with multiple people working on them. Once the project is on GitHub and cloned by you and your colleagues, you can all make changes and commits to the same project. -### Create a Pull Request in GitHub -*Once you are done making changes, you can submit a “pull request," a request for a collaborator to review or comment on your work.* +When setting-up a new repository you have [two options](https://docs.github.com/en/github/getting-started-with-github/types-of-github-accounts): you can invite users to become collaborators to your *personal repository* or groups of people can collaborate across many projects simultaneously with *organization accounts*. Each has different options for [managing settings and permissions](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-user-account-settings). + +Clear communication is vital when collaborating with GitHub. If multiple people are working on a project and all are making changes to the same files, there’s a good chance you will run into conflicts. While git is specifically designed to deal with these sorts of issues, it's important to avoid working on the same sections at the same time. + +### Create a Branch + +A good way to manage users' changes and avoid conflicts is by using [branches](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/managing-branches). Branches are essentially parallel versions of a project. Users can make changes on their branch without affecting the main version of the project. This allows you to review changes and identify possible conflicts before they are incorporated into your project. + +1. Before starting a new branch, click the “Fetch Origin" button at the top right. This will pull down any recently merged changes to the master project. That way, when you start a new branch, you are working off the most up-to-date version of your project. +2. Navigate to where it says “Current Branch” at the top of your GitHub Desktop window. +3. Click the drop-down arrow and select “new branch” to the right of the Filter box. +4. Name your branch. +5. Select “main” where it says “Create branch based on.” This means you are creating a new branch that runs parallel to the main project. Every time you open the project to work on it, make sure you are working in the correct branch. + +Tips for naming branches: + +- Keep branch names concise. +- A branch name should be indicative of the work you are doing or who is working on that particular branch. +- Do not use uppercase letters. +- Separate words with dashes (GitHub won't permit spaces). + +### Submit a Pull Request + +Once you have pushed the changes on your branch, you will be prompted to submit a [pull request](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/creating-an-issue-or-pull-request#creating-a-pull-request). This is a request for your collaborators to review and comment on changes. 1. Click the blue-button that says “Create Pull Request.” This will take you to GitHub.com. -2. Confirm that the branch in the base drop-down menu is the branch where you want to merge your changes. In most cases, this will be the master or main branch. -3. You can leave the default title or type a new title and description for your pull request. -4. On the right-hand side, you will see an option to choose a reviewer. Choose the colleague you would like to review your work. (Note" reviewers must be added as collaborators first.) -5. Click the green-button that says “Create Pull Request” if all your changes are ready for review. Or click the drop-down arrow and choose “Create Draft Pull Request” if you are still making changes that will be included in this particular pull request. +2. Confirm that the branch in the "base" drop-down menu is where you want to merge your changes. In most cases, this will be the master or main branch. +3. You can leave the default title or create a new title and description for your pull request. +4. On the right-hand side, you will see an option to choose the reviewer(s) you would like to overlook your changes. +5. If all your changes are ready for review, click the green-button that says “Create Pull Request." Or click the drop-down arrow and choose “Create Draft Pull Request” if you are still making changes in this particular pull request. + +### Review & Merge Changes -### Review and Merge a Pull Request in GitHub -*Comment on and request changes to a pull request. Once the pull request is approved changes can be merged into the master copy of your project.* +Now you have the opportunity to review changes, provide feedback, or request edits. Once the pull request has been approved, you can [merge](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/merging-a-pull-request#about-pull-request-merges) these changes into the master version of your project. -1. Navigate to “Pull Requests” on the main page of your repository. -2. In the list of pull requests, choose the one you’d like to review. -3. Click “+/- Files changed”. +1. Navigate to "Pull Requests" on the main page of your repository. +2. In the list of pull requests, choose the one you'd like to review. +3. Click "+/- Files changed". 4. Hover over the section of text you would like to comment on. 5. You will see a blue square with a plus mark pop-up. Write your comments here. -6. When you are done commenting click, “Start a Review.” You will have the option to comment, approve, and request changes. -7. Once the pull request has been approved, provided there are no conflicts, you will see a green-button that says “merge pull request.” Click this and, voila, your changes are now incorporated. +6. When you are done commenting click, "Start a Review." You will have the option to comment, approve, and request changes. +7. Once the pull request has been approved, provided there are no conflicts, you will see a green-button that says "merge pull request." Click this and, voila, your changes are now incorporated. + +{{< q-class "box tip" >}} +Merge conflicts will happen when you attempt to merge branches that have competing commits. Read more about [addressing and resolving merge conflicts](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts) in the GitHub documentation. +{{< /q-class >}} + +## Manage Third Party Assets with GitHub + +If you plan to make your repository visible to the public at some point, **you should not commit third-party licensed assets into it**, as this can expose those assets to easy, unlicensed use by other people. We recommend either keeping those assets out of the git record completely and managing them locally or adding them in as a secondary repository that always remains private but can be connected to the main repo as a [git submodule](https://github.blog/2016-02-01-working-with-submodules/). + +### Keeping Assets Out of Git + +For anything you do not want to include in git, you can add a listing for it in your project’s main `.gitignore` file (which you can see when viewing your project in your text editor). You can choose to ignore files by name or by extension, or you can ignore entire directories. + +For instance, you might add all your third-party licensed images into a `licensed` folder in your `content/_assets/images/` folder. By adding `content/_assets/images/licensed` to a new line in your `.gitignore` file, none of those files will be added to the git record and uploaded to GitHub. You’ll only have access to ignored files locally or for collaborators if you provide them copies of the files that they can manually add into their own copies of the repository. + +{{< q-class "box warning" >}} + +- Items added to your `.gitignore` file that have already been committed to your repository will no longer be tracked going forward but will still exist in your project’s history. Permanently removing files is possible, but [much more of a process](https://docs.github.com/en/github/authenticating-to-github/removing-sensitive-data-from-a-repository). + +{{< /q-class >}} + +### Keeping Assets in a Git Submodule + +Where using `.gitignore` can ensure certain sensitive or third-party files won’t get added into a project repository and thus be uploaded to GitHub, it means you have to manually track and manage those files yourself. Another option is to create a second project repository on GitHub to stay private even while your main project is made public. You include that second repository as a submodule within your main repository. + +For instance, you might add all your third-party licensed images into a `my-project-licensed-images` repository and then link that repository as a submodule into the `content/_assets/images/licensed` folder of your main project repository. In this way, Quire can still build the site and output files and preview those images as normal. The files will also be under version control with git and connected to your project (so there’s no manual syncing to do), but you’ll be able to keep them private to everyone except your team or collaborators. + +There are good directions on [working with submodules](https://github.blog/2016-02-01-working-with-submodules/) on GitHub’s blog. Note, however that managing commits to a submodule repository within a repository can be a little tricky, so it’s best not to go this route unless you are comfortable with git and GitHub already or have access to good support. From b1087635767670f3d9b3e76f199bf3d5dcd13f8a Mon Sep 17 00:00:00 2001 From: Erin Cecele Dunigan Date: Wed, 31 May 2023 16:35:56 -0700 Subject: [PATCH 5/5] remove serial publications info --- content/docs-v1/serial-publications.md | 30 -------------------------- 1 file changed, 30 deletions(-) delete mode 100644 content/docs-v1/serial-publications.md diff --git a/content/docs-v1/serial-publications.md b/content/docs-v1/serial-publications.md deleted file mode 100644 index e295464d..00000000 --- a/content/docs-v1/serial-publications.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Use an Existing Quire Project as a Template -weight: 6520 -type: essay -online: false -aliases: - - /documentation/serial-publications/ ---- - -Follow the steps below to use GitHub to create a new project based on a preexisting one. This is especially useful for journals and other serial publications. - -1. In your Finder (macOS) or File Explorer (Windows) find the project you want to make a new version of and duplicate the entire project folder and give it a new name. (If the original project is not already on your computer, clone a fresh copy from GitHub.) - -2. In Terminal (macOS) or PowerShell (Windows) open the new, duplicated project and run these two commands: - - ``` - rm -rf .git - git init - ``` - - (The first removes the existing git history from the old project, the second reinitializes the project as a fresh git repository.) - - -3. In GitHub Desktop chose File > Add Local Repository. Navigate to the duplicated project you just created and chose it. When prompted, click the Initialize Git LFS button. (If not prompted, this command should be done in the command line by running `git lfs install` in the project folder.) - -4. Once added to GitHub Desktop, you’ll see that all the project files will be listed under Changes and will need to be committed. We recommend committing them all at once with the Summary written simply as “Initial commit" plus the name of the original project you duplicated. For example: “Initial commit from my-original-project-name." Other more detailed information can be added in the Description field. - -5. Click Publish repository in the upper right to send the files to github.com. - -6. Run `npm install` in the project to install the necessary software dependencies before previewing and getting to work adding your new content.