-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* using embed package to add walkthrough to cli * fix missing challenge examples * correct println * cleanup comments * improve details in walkthrough * clean up content files * refine first sentences in example markdown and challenges * WIP walkthrough broadened to include config and publish * file ordering adjustment * frontmatter on each content file * update challenges * fix file movement in guide.go * fix filename and link * refactor from user test feedback * extra newling on walkthrough prompt * help message indicates running learn walkthrough
- Loading branch information
Showing
21 changed files
with
1,812 additions
and
57 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
63 changes: 63 additions & 0 deletions
63
app/cmd/embeds/walkthrough/01-example-unit/00-hello-world.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,63 @@ | ||
--- | ||
Type: Lesson | ||
UID: hello-world | ||
--- | ||
|
||
# Hello World | ||
|
||
### !callout-info | ||
If you just ran `learn preview 00-hello-world.md`, you’re now looking at a temporary preview of this file. | ||
|
||
Go back to the command line and run `learn preview .` to preview all example materials. | ||
|
||
Visit the new link and click on the 'Example Unit' to return to this page. | ||
### !end-callout | ||
|
||
This file is written in markdown. You can change any part of it and run | ||
``` | ||
learn preview . | ||
``` | ||
to see your update. You may preview individual files by specifying them for faster previewing. This is the part of the recommended workflow when developing new content and modifying existing content. | ||
|
||
## Your Preview Cohort | ||
|
||
If you look at the URL Learn created where your content can be found, you'll notice a cohort id which belongs to you! Learn cohorts are where instructors and students come together to learn subjects and montior progress, but this cohort is just for your curriculum development. Content you preview will always attach itself to your preview cohort and remain there until your next preview. | ||
|
||
The urls are built using the file names in the project, so each time you preview the same project you can simply refresh the browser to see changes you have made. | ||
|
||
If you just ran `learn preview .` from the root of the walkthrough directory, you might notice new content in the side bar. This content is produced from the walkthrough files: | ||
``` | ||
├── 01-example-unit | ||
│ ├── 00-hello-world.md | ||
│ ├── 01-configuration.md | ||
│ ├── 02-publishing.md | ||
│ ├── 03-markdown-examples.md | ||
│ ├── 04-challenges.md | ||
│ ├── 05-checkpoint.md | ||
``` | ||
|
||
* The 'Configuration' file explains how a repository can be organized into units of content. | ||
* 'Publishing' shows you how to make your materials available for use in a cohort. | ||
* Explore rendering options in 'Markdown Examples'. | ||
* See how Learn enables inline checks for understanding with 'Challenge Examples'. | ||
* Each unit can assess a student's understanding with 'Checkpoint Example'. | ||
|
||
## Generating Content | ||
|
||
The `learn` CLI tool can generate boilerplate markdown for challenges and other custom markdown content (like the callout above) with the command | ||
``` | ||
learn md | ||
``` | ||
|
||
so for example, you can see how a callout markdown can be rendered in a content file with | ||
|
||
``` | ||
learn md co -o | ||
``` | ||
|
||
Try it now and compare it to the content of the `00-hello-world.md` file in your editor. The callout markdown you generated appears much like the callout at the top of the file. | ||
|
||
If you use the `-o` flag the content is sent to `STDOUT`, while the `-m` flag produces a minimal version of the content. | ||
|
||
Each lesson will explore different options with this command. | ||
|
95 changes: 95 additions & 0 deletions
95
app/cmd/embeds/walkthrough/01-example-unit/01-configuration.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,95 @@ | ||
--- | ||
# This is yaml frontmatter which will set values for a generated `autoconfig.yaml` file | ||
# It is not displayed in Learn. | ||
Type: Lesson # Options: Lesson, Checkpoint, Survey, Instructor, Resource | ||
# Lesson is a normal content file | ||
# Checkpoint is a test, which has special configuration options; limit one per unit | ||
# Surveys hold a set of ungraded challenges, and are submitted all at once | ||
# Instructor files are only visible to instructors | ||
# Resources can be linked within content, but will not show up in the navigation side bar | ||
UID: unique-identifier # can be set to any string, must be unique in the repository | ||
# DefaultVisibility: hidden # Uncomment this line to default Lesson to hidden when used | ||
--- | ||
|
||
# Configuration | ||
|
||
If look at this file in your preferred text editor, you'll see content at the top that is not displayed in Learn. This yaml frontmatter is used to set attributes on the content file for Learn. | ||
|
||
You can see an example header by running | ||
``` | ||
learn md fh -o | ||
``` | ||
from your command line. | ||
|
||
### !callout-info | ||
|
||
## Setting Title | ||
|
||
You'll notice the title is not configured in the front matter- it is always derived from the first h1 header in the content file. If none can be found, the file name defines the title. | ||
|
||
### !end-callout | ||
|
||
## Tracking configuration in a file | ||
|
||
After you ran `learn preview .` you'll see a new file in the root of the walkthrough directory named `autoconfig.yaml`. The yaml frontmatter at the top of each file sets the values for the `ContentFiles` key in the `autoconfig.yaml`. | ||
|
||
You can see the format and more information for configuration options by running | ||
``` | ||
learn md cfy -o | ||
``` | ||
from your command line. | ||
|
||
## Controlling Configuration from one file | ||
|
||
Each time the preview is created, the `autoconfig.yaml` file is overwritten. | ||
|
||
However, running `learn preview` or `learn publish` won't generate an `autoconfig.yaml` file if there is already a file named `config.yaml` at the root of the project. Both files are used to define content; `config.yaml` takes precedence over `autoconfig.yaml`, and the latter will rebuild itself on each `preview` or `publish`. | ||
|
||
Go ahead and change the `autoconfig.yaml` file to `config.yaml`, then comment out the `ContentFiles` entry that looks like | ||
``` | ||
- Type: Lesson | ||
Path: /01-example-unit/01-configuration.md | ||
UID: unique-identifier | ||
``` | ||
Then from the root of the project run `learn preview .` again. You'll notice that this content file is now missing! | ||
|
||
Delete the `config.yaml` file entirely, and run `learn preview .` again. It will recreate the `autoconfig.yaml` file again as no config file was discovered. | ||
|
||
## Controlling Unit attributes | ||
|
||
In the configuration file there is a single entry for `Standards`. When the autoconfig was generated, its attributes were read from the file `01-example-unit/description.yaml`. | ||
|
||
You can see an example `description.yaml` file by running | ||
``` | ||
learn md dsy -o | ||
``` | ||
from your command line. | ||
|
||
Each unit directory like `01-example-unit/` should have one `description.yaml` file. | ||
|
||
## Adding more Units | ||
|
||
Create a new Unit directory as a sibling to `01-example-unit/` and name it `02-my-unit/`. Populate it with a single markdown file called `00-playground.md`. From the root of the walkthrough | ||
|
||
``` | ||
mkdir 02-my-unit/ | ||
touch 02-my-unit/00-playground.md | ||
``` | ||
|
||
Write the following contents to your new file: | ||
|
||
``` | ||
--- | ||
Type: Lesson | ||
UID: playground | ||
--- | ||
# Playground | ||
Use this file to experiment! | ||
``` | ||
|
||
Then run `learn preview .` again from the root of the walkthrough directory. Follow the link and notice that you now have _two_ units displayed in your preview. | ||
|
||
We never wrote a `description.yaml` file for our second unit! What did it display for the unit Title and Description? Try adding your own `description.yaml` file inside your `02-my-unit/` directory and change the settings as you see fit. Re-preview to see how Title and Description are now configured. | ||
|
||
Try renaming your new unit directory to `00-my-unit/` and preview again with `learn preview .` to see that the ordering |
49 changes: 49 additions & 0 deletions
49
app/cmd/embeds/walkthrough/01-example-unit/02-publishing.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,49 @@ | ||
--- | ||
Type: Lesson | ||
UID: publishing | ||
--- | ||
|
||
# Publishing | ||
|
||
In order to use curriculum content, it must be published in Learn under a 'block'. Each block represents one remote repository, and each block can have several released versions of curriculum. | ||
|
||
In this way curriculum development of blocks mirrors working on production software. Changes can be made in the repository until a new 'deployment' of curriculum is ready to be created from a single commit. | ||
|
||
Publishing 'deploys' a new release of curriculum content for that block at that commit SHA. Different branches of the same repository can be published to provide greater flexibility when delivering content. | ||
|
||
## Requirements | ||
|
||
In order to publish curriculum, the project must be in a remote git based version control system, and Learn must have permission to access the repository. | ||
|
||
Learn works with GitHub, Gitlab SaaS, and self hosted GitLab instances. Private repositories can be used; when doing so for GitHub, the `github-forge-production` user must have read access to the repository. For GitLab, the `galvanize-learn-production` user must have read access to the project. | ||
|
||
## Push to the Remote | ||
|
||
In the version control system of your choice, create a repository/project ([GitHub](https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github), [GitLab](https://docs.gitlab.com/ee/user/project/)), then commit all contents of the walkthrough: | ||
``` | ||
git add -A | ||
git commit -m "testing learn publish" | ||
git push origin main | ||
``` | ||
|
||
## Publish the curriculum | ||
|
||
From within the project simply run | ||
``` | ||
learn publish | ||
``` | ||
from the command line. | ||
|
||
The `learn` CLI tool will ensure that an `autoconfig.yaml` file exists (unless a `config.yaml` is found) in a commit on the remote, then it will publish the curriculum contents. | ||
|
||
Any errors encountered while attempting to parse the directory will be provided in the event that the publish fails. | ||
|
||
The block will now be discoverable by users with proper access from the [searchable blocks index page](https://learn-2.galvanize.com/blocks). | ||
|
||
## Whats going on with all these UIDs? | ||
|
||
A lot of first time curriculum developers wonder why we have to define so many identifiers within the content, "Shouldn't the database handle this?" they ask. Well, because git repositories back the content rendered in Learn, there needs to be a way for Learn to keep track of the same content _across releases_. | ||
|
||
Suppose a student does work on one released commit of content, then a minor update to the curriculum is prepared and a second release is made for the block. If the lesson the student worked on did not fundamentally change, they still deserve credit for the work done on the prior release. | ||
|
||
Content files, units, and as you'll see challenges all require their own identifiers to keep track of the same content across releases. |
Oops, something went wrong.