Content from Using Markdown

Last updated on 2023-07-24 | Edit this page

Overview

Questions

  • How do you write a lesson using Markdown and sandpaper?

Objectives

  • Explain how to use markdown with The Carpentries Workbench
  • Demonstrate how to include pieces of code, figures, and nested challenge blocks

Introduction

This is a lesson created via The Carpentries Workbench. It is written in Pandoc-flavored Markdown for static files and R Markdown for dynamic files that can render code into output. Please refer to the Introduction to The Carpentries Workbench for full documentation.

What you need to know is that there are three sections required for a valid Carpentries lesson:

  1. questions are displayed at the beginning of the episode to prime the learner for the content.
  2. objectives are the learning objectives for an episode displayed with the questions.
  3. keypoints are displayed at the end of the episode to reinforce the objectives.

Challenge 1: Can you do it?

What is the output of this command?

R 

paste("This", "new", "lesson", "looks", "good")

OUTPUT 

[1] "This new lesson looks good"

Challenge 2: how do you nest solutions within challenge blocks?

You can add a line with at least three colons and a solution tag.

Figures

You can use standard markdown for static figures with the following syntax:

![optional caption that appears below the figure](figure url){alt='alt text for accessibility purposes'}

Blue Carpentries hex person logo with no text.
You belong in The Carpentries!

Callout

Callout sections can highlight information.

They are sometimes used to emphasise particularly important points but are also used in some lessons to present “asides”: content that is not central to the narrative of the lesson, e.g. by providing the answer to a commonly-asked question.

Math

One of our episodes contains \(\LaTeX\) equations when describing how to create dynamic reports with {knitr}, so we now use mathjax to describe this:

$\alpha = \dfrac{1}{(1 - \beta)^2}$ becomes: \(\alpha = \dfrac{1}{(1 - \beta)^2}\)

Cool, right?

Key Points

  • Use .md files for episodes when you want static content
  • Use .Rmd files for episodes when you need to generate output
  • Run sandpaper::check_lesson() to identify any issues with your lesson
  • Run sandpaper::build_lesson() to preview your lesson locally

Content from Open Source and Open Science

Last updated on 2024-05-16 | Edit this page

Overview

Questions

  • What is open science?
  • What is open source development?
  • How are open science and open source development valuable?

Objectives

  • Define open science and open source development
  • Explain pros and cons
  • List attributes that make a research project open
  • Explain how you could publish at the end or beginning

Here’s some example text for the lesson.

Challenge 1: Does USGS support open development?

TRUE or FALSE

USGS allows open development practices which do not violate peer review requirements.

TRUE. You can start a provisional release and follow open development practices. We’ll talk more about that in later episodes.

Key Points

  • Publishing code is a critical part of making science reproducible
  • Code that is published is less likely to contain mistakes or errors
  • Open development makes it easier to make small changes and updates available to an audience, and allows for checks in real-time

Content from Policy

Last updated on 2024-05-16 | Edit this page

Overview

Questions

  • What is an official USGS software information product?
  • When am I required to release my software as an official USGS software information product?
  • When may I release my software as an official USGS software information product?

Objectives

  • Identify the difference between a software project and an official USGS software information product.
  • Identify policy hierarchy relationship between federal, agency, and USGS authorities.
  • Explain requirements for releasing software as an official USGS software information product.

Challenge 1: Identifying relevant policies

Select from which source(s) there exist policies governing the release of official USGS software information products.

A. Federal

B. Departmental

C. Bureau

D. Local

Policies are known to exist for each of (A), (B), and (C) sources. Additionally Science Centers and offices may implement additional policies with which you must comply.

Key Points

  • An official USGS software information production is a point-in-time snapshot of a software product that has received the necessary review and approval to be made publicly accessible.
  • Software must be released as an official USGS software information product before it can be cited by other resources (e.g., data releases, journal articles etc.). Local centers may define other factors necessitating a software release.
  • Any software project may be released as an official USGS software information product given it has received the necessary review and approval.

Content from Creating Metadata for a Software Release

Last updated on 2024-05-16 | Edit this page

Overview

Questions

  • What is a code.json file?
  • How do you create a code.json file?
  • What are the required fields in the code.json file for a USGS Software Release?

Objectives

  • Explain what a code.json file is and how it is used.
  • Create a code.json file with the minimum required fields for a USGS Software Release
  • Validate a code.json file against the defined schema
  • Update a code.json file for a new version of the software

Creating a code.json file

Write a code.json metadata file for this example software release.

JSON 

ADD code.json code here

Key Points

  • A code.json file is a file formatted in JavaScript Object Notation (JSON) and contains project metadata. The code.json file is saved at the top-level of the project.
  • USGS compiles all of the code.json files for public products in GitLab into an inventory that is required by Federal policy.
  • You can use a code.json file template to begin creating your project metadata with the required fields.