Extending 11ty templates

[1000camels]

I am trying to understand best practice for extending my v1 publication.
Should I be editing eleventy.js, all the files in _layout and files in _public
My understanding of how to include new CSS or JS files is to add them to _content/_assets/ and then add the following to eleventy.js

module.exports = function(eleventyConfig) {
eleventyConfig.addPassthroughCopy("bundle.css");
};

But i am not sure where to place the link to the new js or css file

[1000camels]

I am also wondering whether I just changed _includes/components/navigation.js directly

[geealbers]

Thanks for the question @1000camels, this is something we haven't gotten documented yet so I'm glad to be able to answer it here.

For new CSS or JS files, you're right to put them into content/_assets/styles/ and content/_assets/javascript/ respectively. But then instead of using addPassthroughCopy in .eleventy.js, you can import them in content/_assets/javascript/application/index.js where you'll see at the top of the file, listings of the existing CSS and JS files already included in Quire:

// Stylesheets
import '../../fonts/index.scss';
import '../../styles/application.scss'
import '../../styles/screen.scss'
import '../../styles/custom.css'

// Modules (feel free to define your own and import here)
import './canvas-panel'
import './soundcloud-api.min.js'
import { goToFigureState, setUpUIEventHandlers } from './canvas-panel'
import Accordion from './accordion'
import Search from '../../../../_plugins/search/search.js'
import scrollToHash from './scroll-to-hash'

The other option would be to add <script> and <style> tags directly to _includes/components/head.js.

And for modifying layout files, you can ignore the public directory, it is rebuilt on every run of quire build (and frankly we need to do some work to handle it better, we should probably have it gitignored, and also delete it after the _site files are built).

Depending on the need, you'll generally make customizations in the _includes, _layouts, and _plugins directories. With customized v1 Quire projects, one of the big challenges comes if you later want to update your project to the latest version of Quire. For a new feature or bug fix you want, for instance. If the project has not been customized, updating can be as relatively straight forward as starting a fresh project and moving your markdown, yaml, and image files into it. If however, the project has been customized, you'll need to manually copy those customizations over. So the more you can do to minimize the number of different files that are customized, and to carefully document those that are, the easier it will be when it comes time to update. Of course, if you're not expecting to update your project to a newer version of Quire, or won't be using the customizations again in the future, you don't need to worry so much.

Having made customizations myself a lot on Getty's recent Quire projects, here are some strategies I've come to rely on:

• Put a comment at the top (sample) of the modified file, noting that it has been customized, and in what way.
• Keep a running list (sample) of those modified files in the README of the project, with the filepaths and the same brief descriptions you put in the comment
• When possible, create a new file, rather than modifying an existing one. For example, instead of modifying the existing _layouts/essay.liquid, create a _layouts/essay-custom.liquid file and use it as layout: essay-custom in the page YAML.
• Consider using Liquid templating directly in the Markdown files themselves, rather then modifying the underlying JS files. (Since the Liquid will travel with the markdown files more easily from project to project, or through Quire template updates.) For example, if you want a list of keywords to appear at the top of the page, you could add keywords: ['one', 'two', 'three'] to the page YAML and then Liquid {% for word in keywords %}{{ word }}{% endfor %} in the page markdown.