episode_24_projects.qmd

---
title: "Projects: books and websites"
toc: true
---

#### **Challenge**

First, a challenge: What's special about this page title? Specifically, what do I need to do when creating this `.qmd`{style="color:blue"} file to make sure this renders? 

::: {.callout-tip collapse="true"}
## Solution
This page title contains a colon. Since colons are used to separate the key-value pair in the page YAML header, I need to make sure that the title is wrapped in quotation marks. 

:::

## Aims

* Recognise sensible directory structure and appreciate how consistent structure aids reproducibility and collaboration.    
* Understand what a Quarto project is and when to use one.  
* Create and configure a basic Quarto project with `_quarto.yml`{style="color:blue"}.  
* Learn how `_quarto.yml`{style="color:blue"} controls project-wide behavior (rendering, format, options).  


## Project Directory Structure

Project structure and management are an important aspect of reproducible research. We want to build habits that support:

**Transparency**: Other people (and of course - future you) must be able to understand your workflow. 

**Reproducibility**: Define and clearly show what the expected inputs and outputs are. 

**Collaboration**: Having a consistent structure makes it easier for collaborators and teams to work together. 

**Modularity**: Each component of a workflow should be something that can be isolated, tested, and reused in new contexts. 

### Key practices for project layout

Some key practices to keep in mind include:

1. Separate directories for Raw and Processed Data. 

    - Raw and Processed Data will probably be included in your `.gitignore`{style="color:blue"} file so that it is not uploaded to github. 

2. Scripts directories could be split by work stage (*e.g.,* preprocessing/analysis/visualisation) or by type (*e.g.,* R/Bash).

3. Output directories should contain subdirectories for each type of output (figures/tables).

4. Configuration files (`_quarto.yml`{style="color:blue"}, `styles.css`{style="color:blue"}, `README`{style="color:blue"}) should sit in the main project directory.

5. Global naming convention across projects.

#### An example directory structure

my-genomics-project/

├── _quarto.yml

├── index.qmd                # Project overview or README

├── about.qmd                # Team/project info

├── data/

       ├── raw/

       └── processed/

├── scripts/

       ├── qc/

       ├── analysis/

       └── visualizations/

├── results/

       ├── figures/

       └── tables/

├── images/                  # Diagrams, logos

└── docs/                    # Optional: exported PDFs or other formats

#### Group discussion exercise (5 min)

Have you ever inherited a project that did (or did not) adhere to the above principles? How did this impact you? 

Consider your own current projects. If you (or a supervisor) were to leave work at 5pm and not return, what would the inheritors of this project think? 

How much work would be involved in getting your current or previous projects from where they are now to a point where you would be happy to receive them?

## Quarto Projects

So far we have worked under the assumption that we are creating a single, brief document (*e.g.,* a 10-page pdf, short html document *etc.,*). A **project** is a larger structure and will usually contain multiple individual documents all linked together. Examples of projects are books or multi-page websites. 

We should also think about projects in terms of directory structure. We want to develop the habit of creating a clear and consistent directory structure for each of our projects, one that will be easy for other users to navigate and interpret. 


### Quarto Projects and _quarto.yml

Specifically, a project is a directory that contains a high level file that provides information and structure to the other files: the `_quarto.yml`{style="color:blue"} file. The `_quarto.yml`{style="color:blue"} file is required to link individual pages together and provides options for navigation menus. Once a `_quarto.yml`{style="color:blue"} file is in place in a directory, rendering any `.qmd`{style="color:blue"} file in the directory will render all files in that directory - but only those that are linked through the `_quarto.yml`{style="color:blue"} file will appear in the document. 

If you have been following along you should have two `.qmd`{style="color:blue"} files (something like "getting-started.qmd" and "code-in-quarto.qmd' - depends what you named them!). We will now build a new `_quarto.yml`{style="color:blue"} file and use it to link the two existing pages into a single site. We will break this simple `_quarto.yml`{style="color:blue"} into three sections: project information, website information, and format information.

::: {.callout-tip collapse="true"}
## What if we **don't** want to render a doc in the directory?

Sometimes a directory will contain files we don't want to render - they may be large, or basic scratch notes, *etc.,*. To exclude files from the render process, rename them to start with an underscore (like with the _quarto.yml file). 
:::


#### Project information


This file is essentially a YAML header for the whole project. Options here will be global for all files. We can see three discrete blocks of information in the above example: 


1. First we specify information about the project itself. This will include specifying the *type* of project, in this case website but alternatively a book/article/*etc.,*. Also nested under the project key we are going to specify the output directory for all rendering - we could render straight into the working directory, but we want to abide by good project structure and specify where our output files are going. We need to specify the output dir as "docs" to be able to publish the website later. 

2. Second we have a block containing information about the output document. Because we are working on a website, we used the "website:" key and will use this to set the title and add a navigation bar. Under the navigation bar we link all the .qmd files we want to include with this website. When we are manually selecting .qmd files to include we must set both the title with the text argument and the filename with the href argument. There are *a lot* of additional options available to us in this block such as: top/side navigation bars of different styles, auto-generated contents, LinkedIn/Github icons *etc.,* which we will cover later. 

3. Third we can control the look of the website with format options. We specify that we are working with an html-type output and can choose from a set of pre-built themes to customise the look of the document. We can also specify a css file, where we provide a styles.css file that further customises our website (*e.g.,* brand colours, hyperlink visuals). We will look at creating a styles.css file later. 

An example `_quarto.yml`{style="color:blue"}  file looks like:

![_quarto.yml](figures/quartoYML.png)

Remember, the _quarto.yml file is essentially a YAML header for the whole document and is very fussy about indentation, spacing (between key-value pairs), and all format arguments.


#### **Exercise:** Create your own _quarto.yml, add themes and options (8 min)

1. Create a text document in RStudio
2. Copy-paste the following text (change file names to your file names!):

```bash
project:
  type: website
  output-dir: docs

website:
  title: "My Quarto Site"
  navbar:
    left:
      - text: "Getting started"
        href: getting-started.qmd
      - text: "Code blocks"
        href: code-in-quarto.qmd

format:
  html:
    theme: default
```
> Note: the formatting will go weird if you copy-paste into a new R script. Make sure it is a new text file!

3. Save this file as `_quarto.yml`{style="color:blue"}
4. Click render from one of the existing `.qmd`{style="color:blue"} files. You cannot render from the `_quarto.yml`{style="color:blue"} file itself!
5. Explore your new webpage! 🥳

6. Now, you can change the theme in the `_quarto.yml`{style="color:blue"} file from default to one of the 25 pre-built options (listed below). Render the document and view the outcome ✨

::: {.callout-tip collapse="true"}
## **Pre-constructed themes**

    default
    cerulean
    cosmo
    cyborg
    darkly
    flatly
    journal
    litera
    lumen
    lux
    materia
    minty
    morph
    pulse
    quartz
    sandstone
    simplex
    sketchy
    slate
    solar
    spacelab
    superhero
    united
    vapor
    yeti
    zephyr

:::

7. Options: Immediately under the navbar line, add a new line (indented from navbar) and add `pinned: true`. What effect does this have? 

## Summary

* Sensible directory structures enhance reproducibility and make collaboration easier.   
* Quarto projects are a directory containing multiple `.qmd`{style="color:blue"} files linked by a `_quarto.yml`{style="color:blue"} document.  
* Basic `_quarto.yml`{style="color:blue"} files control the structure of the output website/book, and can control all visual elements.