diff --git a/docs/carpentries-workbench/callout_blocks.md b/docs/carpentries-workbench/callout_blocks.md deleted file mode 100644 index 45f00db..0000000 --- a/docs/carpentries-workbench/callout_blocks.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Callout Blocks -layout: default -parent: Carpentries Workbench -nav_order: 2 ---- - -The Carpentries Workbench comes with a customized version of Pandoc. What is pandoc? Pandoc is a tool that allows for custom callout blocks. -These blocks can be used in a variety of ways from challenge questions to discussion points. A formative list of all the [Callout Blocks](https://carpentries.github.io/sandpaper-docs/component-guide.html) supported by the Carpentries are found in that link. - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - -## Callout Blocks - -Callout blocks are created through ***fenced divs***. These are a pair of 3 or more ***:::*** at the beginning and end of what you are -trying to callout. - -![Default Callout Block]({{ site.baseurl }}/assets/img/workbench/default_callout.png) - -The code for this callout block goes as follows: - -``` -::: callout -## Callout Block -This is what a default Callout block looks like -::: -``` - -The structure of the callout block starts with at least 3 colons (:::) followed by the type of callout that you want to use. You can find a list of -supported callout blocks [here](https://carpentries.github.io/sandpaper-docs/component-guide.html). After that comes the content followed by an ending set of colons. - - Note that you don't need to have exactly 3 colons, you need ***AT LEAST*** 3 colons in order to create a callout block. - -``` -::: Name of the callout block you want to use -## Heading -Content -::: <- ending set of colons -``` - -## Special Callout Blocks - -### Questions and Objectives -Every episode should contain a ***questions*** and ***objectives*** callout block at the start. This outlines an overview for the episode that is -being taught. They are displayed side by side in the browser and will look like this. - -![Questions and Objective Callout Block]({{ site.baseurl }}/assets/img/workbench/Q_O.png) - -The code for this looks like this: - -``` -::: 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 -::: -``` - -*Note that these two callout blocks are special and have to follow each other in order to be displayed properly. Another thing -to note is that they are using markdown's bullet point format putting '-' in the beginning of each statement.* - -### Challenges -Challenges should be frequently utilized throughout a lesson. The Carpentries has a special Challenge block that looks like this. - -![Challenge Block]({{ site.baseurl }}/assets/img/workbench/challenge.png) - -The ***Challenge*** block is accompanied by a ***solution*** block with the ability to add a ***hint*** block as well. the code for that -looks something like this. - -``` -:::::::::::::::::::::::::::::::::: challenge -## Challenge title (optional) -Challenge -::::::::::::::::::: hint -your hint -::::::::::::::::::: -::::::::::::::::::: solution -### Title (optional) -Solution -::::::::::::::::::: -:::::::::::::::::::::::::::::::::: -``` - -In this callout block, we nest the ***solution*** and ***hint*** blocks within the ***challenge*** block. This is so the heirarchy is -preserved. Another thing to note is the Title in ***solution*** block. If you choose to include a title then the title would replace the -***SOLUTION*** tab with the title that you give it. Another thing is that a ***challenge*** block should be accompanied by a ***solution*** block but that is optional. The ***hint*** block is completely optional and up to user descretion. - -Note that the solution and hint tabs will be closed at first. - -There are several other callout blocks that are supported and you can find more information about them [here](https://carpentries.github.io/sandpaper-docs/component-guide.html) \ No newline at end of file diff --git a/docs/carpentries-workbench/index.md b/docs/carpentries-workbench/index.md deleted file mode 100644 index 07a178d..0000000 --- a/docs/carpentries-workbench/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Carpentries Workbench -layout: default -permalink: /docs/carpentries-workbench -has_children: true -nav_order: 4 ---- - -# Carpentries Workbench - -This is the workbench that the lesson authors will use. You guys can familiarize yourself with the workbench by going through these guides. -[A dive into the Workbench](https://carpentries.github.io/sandpaper-docs/) and [Curriculum Development with the workbench](https://cdh.carpentries.org/). -These guides offer an introduction into the workbench and how it works and should be used. The following documentation is something you can -look back at to get a better feel and understanding of the important elements in the workbench. \ No newline at end of file diff --git a/docs/carpentries-workbench/sandpaper.md b/docs/carpentries-workbench/sandpaper.md deleted file mode 100644 index 18185b7..0000000 --- a/docs/carpentries-workbench/sandpaper.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Into Sandpaper -layout: default -parent: Carpentries Workbench -nav_order: 1 ---- - -## What is Sandpaper? - -Sandpaper is the an R Studio package that is used in the Carpentries Workbench. It is used to run, preview, and build Lessons locally. -It comes with a suite of commands that help you build, preview, and run the site. You can preview these commands in the R Studio Console by -typing out "sandpaper::" . A list of commands should appear after the "::" . Below we will document and describe several key commands. -Each command also has a short description that you can read. -![R Studio Console Accepts Sandpaper Commands]({{ site.baseurl }}/assets/img/workbench/sandpaper_console.png) - -### sandpaper::create_lesson() - -This command in R Studio will create an empty Carpentries Workbench in the path provided in its argument. This is a good message to use in R Studio -if you want to create a new lesson using the Workbench. An example would be ***sandpaper::create_lesson("/filepath/Carpentries Guide")***. This command -would create a new workbench with the name **Carpentries Guide** in the path you specified. - - - -### sandpaper::draft_episode_md() & sandpaper::draft_episode_rmd() - -This command takes in 1 input, that being the title of the episode you want to create. You would use this command when you have a -draft for an episode but don't yet want to publish it. It will create a template for the episode under the episodes/ folder and you can -edit it from there like a normal lesson. To do so, you will run the following command in the RStudio console, ***sandpaper::draft_episode_md("Episode Title")***. After you are completed and want to move the episode into the lesson, you will have to use the ***sandpaper::move_episode("Episode Name")*** -command. This command will help you move the episode into the config file without you having to manually do it. -Of course, if you want to create an R Markdown episode use the ***rmd()*** otherwise use the ***md()***. - -#### Before Episode Creation -![Episode Folder Before]({{ site.baseurl }}/assets/img/workbench/draft_before.png) - -#### Episode Creation Command -![Episode Folder]({{ site.baseurl }}/assets/img/workbench/draft_command.png) - -#### After Episode Creation -![Episode Folder After]({{ site.baseurl }}/assets/img/workbench/draft_after.png) - -### sandpaper::create_episode_md() & sandpaper::create_episode_rmd() - -These set of commands have the same functionality as the commands above except for the fact that you don't need to use the ***move_episode()*** function. -These commands will automatically create a new episode and input it into the config file so that you will be able to directly see any changes made -to it. - -### sandpaper::serve() - -Sandpaper::serve() is a command that will build and display your site in the bottom-right viewer of R Studio. (Tip: You can pop this view out -into it's own window) This command will incrementally update your Lesson as you make any changes. It is great for viewing changes in a quick manner -without having to constantly running ***sandpaper::build_lesson()*** or other build commands. - -![Sandpaper::serve() and its Output]({{ site.baseurl }}/assets/img/workbench/sandpaper_serve.png) - -If you look closely you a small icon to the right of the broom in the viewer window. If you click on that you will be able to pop-out the -episode into a browser window. - -![Pop-out Icon]({{ site.baseurl }}/assets/img/workbench/pop_out.png) - -There are more ***sandpaper::*** commands if you browse around in the R Studio console but these are the most important ones that will be used. \ No newline at end of file diff --git a/docs/repo-setup/clone-repo.md b/docs/repo-setup/clone-repo.md deleted file mode 100644 index 8c3f3ed..0000000 --- a/docs/repo-setup/clone-repo.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Clone a Repository to your Local Device -layout: home -parent: Lesson Repository Setup -nav_order: 2 ---- - -# Clone a Repository to your Local Device -1. **Fork the [Workbench Markdown template](https://github.com/new?template_name=workbench-template-md&template_owner=carpentries) into your desired organization.**\ - - You can select an organization from the drop down arrow in Owner. Please name the repository to reflect your lesson proposals. -![Create a new Repository]({{ site.baseurl }}/assets/img/repo-setup/clone-repo1.png) -2. **Clone the repository to your local device. Open R studio, and go to `File -> New Project -> Version Control -> Git`.**\ -\ -![file -> new project]({{ site.baseurl }}/assets/img/repo-setup/clone-repo2a.png)\ -![go to Version Control]({{ site.baseurl }}/assets/img/repo-setup/clone-repo2b.png)\ -![choose Git]({{ site.baseurl }}/assets/img/repo-setup/clone-repo2c.png) -3. **The repository URL is the GitHub website link to your repository.** - - paste the URL, and name the folder. This should clone the repository onto your local device successfully.\ - ![Your GitHub repo link]({{ site.baseurl }}/assets/img/repo-setup/clone-repo3a.png)\ - ![Paste the URL here.]({{ site.baseurl }}/assets/img/repo-setup/clone-repo3b.png) - \ -4. **Connect your local device to your online Repository** - - Run `git config remote.origin.url git@github.com:[your-github-username]/[your-online-repo-name].git` in the R Studio Terminal. You can find the link from the online repository.\ - ![Paste the URL here.]({{ site.baseurl }}/assets/img/repo-setup/clone-repo4.png) - - NOTE: If it is your first time adding a SSH key, it will ask you if you want to build a connection. You should answer yes. - \ -5. **You have successfully connected your local device to the online repository. Congratulations!** πŸŽ‰πŸŽ‰ - - - - diff --git a/docs/repo-setup/index.md b/docs/repo-setup/index.md deleted file mode 100644 index 47caac6..0000000 --- a/docs/repo-setup/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Lesson Repository Setup -layout: home -permalink: /docs/repo-setup -has_children: true -nav_order: 3 ---- \ No newline at end of file diff --git a/docs/repo-setup/ssh-setup.md b/docs/repo-setup/ssh-setup.md deleted file mode 100644 index 8527989..0000000 --- a/docs/repo-setup/ssh-setup.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Set up your SSH key -layout: home -parent: Lesson Repository Setup -nav_order: 1 ---- - -# Create SSH Key and Connect Your Local Device to an Online Repository -1. **Install [git(Mac)](https://carpentries.github.io/workshop-template/#shell-windows) / [git(Windows)](https://carpentries.github.io/workshop-template/#shell-windows), [R](https://carpentries.github.io/workshop-template/#shell-windows), and [R Studio](https://posit.co/download/rstudio-desktop/#download).** - - If you have git installed, use `git –-version` to check the version of git. - - Git Version 2.41.0 is recommended, but not required. - - Mac: Use `brew upgrade git` to update to the latest version. - - Windows: Use `git update-git-for-windows` to update git to the latest version. -1. **Install Required Packages in R Studio Console**\ - ![img]({{ site.baseurl }}/assets/img/repo-setup/1.jpg)\ - - Navigate to R Studio, and then go to console, and run these commands: - - `CRANoptions(repos = c(carpentries = "https://carpentries.r-universe.dev/", CRAN = "https://cran.rstudio.com/"))` - - `install.packages(c("sandpaper", "varnish", "pegboard","tinkr"))` -1. **Test the installation in R Studio Console** - ``` - rmarkdown::pandoc_version() - tmp <- tempfile() - sandpaper::no_package_cache() - sandpaper::create_lesson(tmp, open = FALSE) - sandpaper::build_lesson(tmp, preview = FALSE, quiet = TRUE) - fs::dir_tree(tmp, recurse = 1) - ``` -1. **Link to Git in R Studio** - - Tools -> Global Options\ - ![img]({{ site.baseurl }}/assets/img/repo-setup/2a.png) - - Link the git.exe to Git executable\ - ![img]({{ site.baseurl }}/assets/img/repo-setup/2b.png) -1. **Generate SSH key in R Studio** - - Tools -> Global Options\ - ![img]({{ site.baseurl }}/assets/img/repo-setup/3a.png) - - When you create an SSH key, it generates two files. One is a private file that can only be used on your local machine, and another one is the public key that needs to be added to your github account. -1. **Copy Public Key** - - Click on "View public key" to copy your public key\ - ![img]({{ site.baseurl }}/assets/img/repo-setup/4.png) - -1. **Add Public Key to your GitHub Account** - - Settings -> SSH and GPG keys\ - ![img]({{ site.baseurl }}/assets/img/repo-setup/5a1.png)\ - ![img]({{ site.baseurl }}/assets/img/repo-setup/5a2.png) - - Click on New SSH Key. Name it, and paste the public SSH key that was copied earlier. -1. **Add SSH key to SSH agent.** - - Open Terminal in R Studio, and run these commands: - ``` - eval $(ssh-agent -s) - ssh-add ~/.ssh/id_ed25519 - ssh -T git@github.com - ``` - - If you’re on macOS Sierra 10.12.2 and higher, you need to do one more thing. Create a file `~/.ssh/config` with these contents:\ - ``` - Host * - AddKeysToAgent yes - UseKeychain yes - IdentityFile ~/.ssh/id_ed25519 - ``` -1. **Test if you added SSH key successfully** - - Run `ssh -T git@github.com` - -