Contributing to the Nexus Website

The Nexus website is built with Quarto – an open‐source scientific and technical publishing system that lets you write documents and websites in a plain markdown format (with a .qmd extension). This guide explains how to add new blog and calendar posts to the site, how to use Quarto markdown, what tools can be used for editing, and how to deploy your changes.

Note: The examples below assume that the website’s content is organized in directories (for example, a blog/ folder for blog posts and a calendar/ folder for calendar posts). If your site uses a different structure, adjust the file paths accordingly.

1. Prerequisites

Before you start, make sure you have the following installed: - Quarto: Download and install Quarto from quarto.org. - RStudio or VS Code:
- RStudio has excellent support for Quarto and is popular among data scientists. - Alternatively, you can use Visual Studio Code with the Quarto extension. - Git: Ensure you have Git installed so you can clone, commit, and push changes. (See Git’s official site for installation details.)

2. Repository Structure Overview

When you clone the repository (e.g., https://github.com/nexus-exposomics/nexus), you should see files and directories similar to the following:

nexus/ ├── _quarto.yml # Global site configuration ├── index.qmd # Homepage ├── blog/ # Directory for blog posts │ └── sample-post.qmd ├── calendar/ # Directory for calendar events (if separate) │ └── sample-event.qmd └── … # Other assets and resources

If the site’s blog or calendar content lives in a different folder, please adjust the instructions below accordingly.

3. Writing a New Post

All content pages (blog posts, calendar events, etc.) are written as Quarto markdown (.qmd) files. Each file begins with a YAML header that specifies metadata like title, date, and formatting options.

3.1. Adding a Blog Post

  1. Navigate to the Blog Directory:
    Open the blog/ directory in your preferred editor (e.g., RStudio or VS Code).

  2. Create a New File:
    Create a new file (e.g., my-new-blog-post.qmd).

  3. Write the YAML Header and Content:
    Here’s an example template for a blog post:

    ```yaml

    title: “My New Blog Post” author: “Your Name” date: 2025-02-09 categories: [blog] tags: [Quarto, R, Data Science] format: html —

    Introduction

    Welcome to my new blog post! Write your content here using standard markdown. For example, you can include bold text, italics, and even embed code.

    A Code Example

    ```r # This is an R code chunk summary(cars)

  4. Save the File.

3.2. Adding a Calendar Event

If your website uses a dedicated calendar section (for instance, in the calendar/ folder), the process is very similar.

  1. Navigate to the Calendar Directory:
    Open the calendar/ folder.

  2. Create a New File:
    Create a new file (e.g., upcoming-event.qmd).

  3. Write the YAML Header and Content:
    Use a template like the following:

```yaml 31b8e172-b470-440e-83d8-e6b185028602:dAB5AHAAZQA6AFoAUQBBAHgAQQBEAGcAQQBNAFEAQQA1AEEARABZAEEATQBBAEEAMQBBAEMAMABBAE0AQQBCAGgAQQBHAE0AQQBaAEEAQQB0AEEARABRAEEAWgBnAEIAaABBAEcAVQBBAEwAUQBBADQAQQBHAEkAQQBPAFEAQQA1AEEAQwAwAEEATwBRAEIAagBBAEQARQBBAFkAZwBBADMAQQBHAEkAQQBaAEEAQQAzAEEARwBNAEEATQBBAEIAbQBBAEQARQBBAAoAcABvAHMAaQB0AGkAbwBuADoATQB3AEEAegBBAEQATQBBAE0AdwBBAD0ACgBwAHIAZQBmAGkAeAA6AAoAcwBvAHUAcgBjAGUAOgBMAFEAQQB0AEEAQwAwAEEAQwBnAEIAMABBAEcAawBBAGQAQQBCAHMAQQBHAFUAQQBPAGcAQQBnAEEAQwBJAEEAVgBRAEIAdwBBAEcATQBBAGIAdwBCAHQAQQBHAGsAQQBiAGcAQgBuAEEAQwBBAEEAVABnAEIAbABBAEgAZwBBAGQAUQBCAHoAQQBDAEEAQQBSAFEAQgAyAEEARwBVAEEAYgBnAEIAMABBAEMASQBBAEMAZwBCAGsAQQBHAEUAQQBkAEEAQgBsAEEARABvAEEASQBBAEEAeQBBAEQAQQBBAE0AZwBBADEAQQBDADAAQQBNAEEAQQB6AEEAQwAwAEEATQBRAEEAMQBBAEEAbwBBAGIAQQBCAHYAQQBHAE0AQQBZAFEAQgAwAEEARwBrAEEAYgB3AEIAdQBBAEQAbwBBAEkAQQBBAGkAQQBGAFkAQQBhAFEAQgB5AEEASABRAEEAZABRAEIAaABBAEcAdwBBAEkAQQBBAHYAQQBDAEEAQQBUAHcAQgB1AEEAQwAwAEEAYwB3AEIAcABBAEgAUQBBAFoAUQBBAGcAQQBFAHcAQQBiAHcAQgBqAEEARwBFAEEAZABBAEIAcABBAEcAOABBAGIAZwBBAGkAQQBBAG8AQQBZAHcAQgBoAEEASABRAEEAWgBRAEIAbgBBAEcAOABBAGMAZwBCAHAAQQBHAFUAQQBjAHcAQQA2AEEAQwBBAEEAVwB3AEIAagBBAEcARQBBAGIAQQBCAGwAQQBHADQAQQBaAEEAQgBoAEEASABJAEEAWABRAEEASwBBAEcAWQBBAGIAdwBCAHkAQQBHADAAQQBZAFEAQgAwAEEARABvAEEASQBBAEIAbwBBAEgAUQBBAGIAUQBCAHMAQQBBAG8AQQBMAFEAQQB0AEEAQwAwAEEACgBzAHUAZgBmAGkAeAA6AA==:31b8e172-b470-440e-83d8-e6b185028602

Event Details

Join us for the upcoming Nexus event where we discuss the latest in exposomics research.

Time: 10:00 AM – 12:00 PM
Location: Zoom / Conference Room XYZ

For more details, please visit our event page.

4.  Save the File.
  1. Learning Quarto Markdown

Quarto markdown (.qmd) is similar to standard markdown with a few extra features. Here are some useful tips and resources: • YAML Front Matter: The block at the top of each .qmd file (between — lines) sets document metadata. See Quarto’s Front Matter documentation for more details. • Code Execution and Literate Programming: You can include executable code chunks in R, Python, or other supported languages. Check out Quarto’s code execution docs for syntax and options. • Formatting and Styling: Standard markdown syntax works (headings, lists, links, images, etc.). Visit the Quarto markdown guide for a refresher. • Interactive Content: Quarto also supports interactive elements and advanced features such as citations, cross-references, and more. Explore Quarto’s advanced features.

  1. Tools for Editing Quarto Websites

You have several options for editing Quarto documents: • RStudio: RStudio natively supports Quarto. Open the .qmd file, edit the content, and use the “Render” or “Preview” button to see your changes in a browser. • Visual Studio Code: Install the Quarto extension for syntax highlighting, live preview, and more. • Command Line: You can render your entire site by running the following command in your repository’s root directory:

quarto render

For a live preview, run:

quarto preview

  1. Pushing Changes to the Web

After you’ve added or edited posts locally, follow these steps to update the live website: 1. Test Locally: Run quarto preview (or render the site using your editor) to verify that your changes look as expected. 2. Commit Your Changes: • Open your terminal (or use RStudio’s Git pane). • Stage your changes:

git add .

•   Commit your changes:

git commit -m “Add new blog post: My New Blog Post”

3.  Push to GitHub:

git push origin main

(Replace main with your branch name if different.)

4.  Deploy the Site:

The Nexus website may be hosted using one of several approaches: • GitHub Pages: If GitHub Pages is enabled for the repository, pushing to the main branch (or a designated branch) will update the live site automatically. • Netlify/Vercel or Other CI/CD: If you use a service like Netlify or Vercel, the push will trigger a build process that deploys your changes. • Custom Server: If you deploy to your own server, follow your standard deployment procedure (for example, pulling from GitHub on the server).

For more detailed deployment instructions, check the documentation for your hosting service or refer to the Quarto deployment docs.

  1. Additional Resources • Quarto Official Documentation: https://quarto.org/docs/ • RStudio and Quarto: https://rstudio.com/products/rstudio/features/#quarto • Git Documentation: https://git-scm.com/doc

  2. Summary

    1. Create a new .qmd file in the appropriate folder (e.g., blog/ or calendar/).
    2. Fill in the YAML header and content using Quarto markdown.
    3. Test your changes locally with quarto preview.
    4. Commit and push your changes via Git.
    5. Deploy your updates by following your website’s hosting workflow.

By following these steps, you can easily add new blog posts and calendar events to the Nexus website.

Happy writing and contributing!

To use this file: 1. Save the above content into a file named CONTRIBUTING.md in your repository. 2. Customize any sections as needed based on your specific project structure or deployment workflow. 3. Share it with your contributors so everyone knows how to add new posts and update the website.