Introduction

Welcome to the Just-the-docs documentation home page for the Map & Data Library at the University of Toronto Libraries. Here you will find the guide on how to edit our just-the-docs based sites

Structure of MDL just-the-docs sites

There are two main types of just-the-docs sites hosted by MDL via GitHub Pages:

1. General guides sites: These are the main how-to-guides for various topics, such as GIS, data visualization, etc. It is meant to be browsed by patrons, and was hosted on MDL Drupal site previously.
2. Special sites: These are just-the-docs sites that serve specific purposes, such as search portals, documentation for editing, etc.

How the sites are related

flowchart TD
    accTitle: Relationships between the MDL just-the-docs sites
    accDescr: jtd-template is a GitHub template used to create each new guide. jtd-theme provides the look of the guides and this site. tutorials-search lists every guide. jtd-edit-setup documents how to edit all of them.
    theme["jtd-theme<br/>(remote theme)"]
    template["jtd-template<br/>(GitHub template)"]
    guides["General guide sites<br/>(one repository per guide)"]
    search["tutorials-search<br/>(search portal)"]
    editsetup["jtd-edit-setup<br/>(this site)"]

    template -- "Use this template<br/>(one-time copy)" --> guides
    theme -. "remote_theme<br/>(applied on every build)" .-> guides
    theme -. "remote_theme" .-> editsetup
    search -- "lists and links to<br/>(guides.yml)" --> guides
    guides -- "sidebar title links back to" --> search
    editsetup -- "documents how to edit" --> guides

• jtd-theme controls the layout, styles and components of the guide sites and this site. A change to the theme appears on those sites the next time each one is built.
• jtd-template is a GitHub template. A new guide is created from it with the Use this template button, which copies its files once. Later changes to the template do not reach existing guides. See Breaking changes to _config.yml for the changes that existing guides need to apply by hand.
• General guide sites are created from the template and use the theme. Each guide has its own repository.
• tutorials-search is the entry point for patrons. It lists every guide from its guides.yml file, so it must be updated whenever a guide is created, renamed or removed. See Edit the tutorials-search Records.
• jtd-edit-setup (this site) is the documentation for editing all of the above.

Special sites

Name	Url	Repository	Description	When to edit	Editing guide
MDL just-the-docs editing guide	https://mdlutoronto.github.io/jtd-edit-setup/	https://github.com/MDLutoronto/jtd-edit-setup	This site. Serve as the editing guide and documentation for all the MDL just-the-docs site.	When there's new guidance needed for editing just-the-docs site	https://mdlutoronto.github.io/jtd-edit-setup/
MDL Gudies Search Page	https://mdlutoronto.github.io/tutorials-search/	https://github.com/MDLutoronto/tutorials-search	The search catalouge for MDL guides.	When a new guide is created, existing guide metadata needs to be changed, or an old guide is to be deleted.	https://mdlutoronto.github.io/jtd-edit-setup/edit-tutorials-search
MDL just-the-docs template	/	https://github.com/MDLutoronto/jtd-template	A GitHub repository template. For creating a new just-the-docs site with MDL theme applied.	Almost never unless there's breaking changes for newer version for just-the-docs.	https://github.com/MDLutoronto/jtd-template/blob/main/README.md
MDL just-the-docs theme	/	https://github.com/MDLutoronto/jtd-theme	The remote theme to be applied to every repository created using the jtd-template.	When new UI components that apply to ALL just-the-docs MDL sites need to be updated.	https://github.com/MDLutoronto/jtd-theme/blob/main/README.md