Skip to content

Commit f3fc1f2

Browse files
kefortneykefortney
committed
large rewrite and expansion
1 parent a265077 commit f3fc1f2

16 files changed

Lines changed: 3488 additions & 41 deletions

‎README.md‎

Lines changed: 141 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,177 @@
1+
# Open Resource Library
2+
13
[![DOI](https://zenodo.org/badge/715627164.svg)](https://zenodo.org/doi/10.5281/zenodo.11508637)
24

3-
# Open Resource Library
5+
An open source toolkit for students and researchers getting started with open source software development.
6+
7+
Maintained by [VERSO (Vermont Research Open Source Program)](https://verso.w3.uvm.edu) at the University of Vermont.
8+
9+
**Live site:** [verso-uvm.github.io/Open-Resource-Library](https://verso-uvm.github.io/Open-Resource-Library)
410

5-
Learn, explore, and create open source practices.
11+
---
612

7-
UVM
13+
## What's Inside
14+
15+
The library is organized into three sections:
16+
17+
- **Concepts** — foundational ideas: version control, testing, debugging, APIs, CI/CD, licensing, ethics, and more
18+
- **Tools** — practical guides: Git, GitHub, VS Code, Python, Docker, pyenv, SSH, and more
19+
- **VERSO Standards** — project conventions for commit messages, micro-commits, and AI use
20+
21+
---
822

923
## Contributing
1024

11-
**TODO**
25+
Contributions are welcome — from fixing typos to adding entirely new pages. All skill levels are welcome.
26+
27+
### Getting Started
1228

13-
### Local development
29+
1. **Fork** the repository on GitHub
30+
2. **Clone** your fork locally
31+
3. **Create a branch** for your changes: `git checkout -b your-branch-name`
32+
4. Make your changes (see [Editing Content](#editing-content) below)
33+
5. **Commit** with a descriptive message
34+
6. **Push** your branch and open a **Pull Request**
1435

15-
To work on the Open Resource Library (ORL) locally, you must have [Bun](https://bun.sh) installed, as it is the runtime and package manager of choice for the ORL.
36+
### Local Development
1637

17-
##### Install dependencies
38+
You need [Bun](https://bun.sh) installed. Bun is the runtime and package manager used by this project.
39+
40+
**Install Bun:**
41+
42+
```bash
43+
# macOS / Linux
44+
curl -fsSL https://bun.sh/install | bash
45+
46+
# Windows (PowerShell)
47+
powershell -c "irm bun.sh/install.ps1 | iex"
48+
```
49+
50+
**Install dependencies:**
1851

1952
```bash
2053
bun i
2154
```
2255

23-
##### Start the development server
56+
**Start the development server:**
2457

2558
```bash
2659
bun start
2760
```
2861

29-
This will open a browser window to [localhost:3000](http://localhost:3000), which will be updated live with any changes you make to the library.
30-
(Note: you may append `--no-open` to this command to prevent the opening of a new browser window)
62+
This opens a browser window at [localhost:3000](http://localhost:3000) and updates live as you edit files. Add `--no-open` to prevent the browser from opening automatically.
3163

32-
##### Build the site
64+
**Build the site:**
3365

3466
```bash
3567
bun run build
3668
```
3769

38-
##### Preview the built site
70+
**Preview the built site:**
3971

4072
```bash
4173
bun serve
4274
```
4375

44-
This also open a browser window to [localhost:3000](http://localhost:3000) which will allow you to preview what the site will look like in production.
45-
(As with the dev server, `--no-open` may be provided to prevent the opening of a new browser window)
76+
This also opens [localhost:3000](http://localhost:3000) so you can preview what the site will look like in production.
77+
78+
---
79+
80+
## Editing Content
81+
82+
All content lives in the `docs/` directory as Markdown files. Each subdirectory is a category in the sidebar.
83+
84+
### Directory Structure
85+
86+
```text
87+
docs/
88+
├── introduction.md # Landing page
89+
├── concepts/ # Conceptual guides
90+
│ ├── _category_.yml # Sidebar config for this category
91+
│ ├── apis.md
92+
│ ├── ci_cd.md
93+
│ ├── command_line.md
94+
│ ├── debugging.md
95+
│ ├── documentation.md
96+
│ ├── package_management.md
97+
│ ├── security_basics.md
98+
│ ├── testing.md
99+
│ ├── version_control.md
100+
│ └── ...
101+
├── tools/ # Tool-specific guides
102+
│ ├── _category_.yml
103+
│ ├── docker.md
104+
│ ├── git.md
105+
│ ├── github.md
106+
│ ├── python.md
107+
│ ├── pyenv.md
108+
│ ├── ssh.md
109+
│ ├── vscode.md
110+
│ └── ...
111+
└── verso-standards/ # VERSO project conventions
112+
├── _category_.yml
113+
├── commit-messages.md
114+
└── ...
115+
```
116+
117+
### Adding a New Page
118+
119+
1. Create a `.md` file in the appropriate category directory
120+
2. Start with a `#` heading — this becomes the page title and sidebar label
121+
3. Write content using standard Markdown (see [Markdown Guide](https://www.markdownguide.org))
122+
4. Docusaurus admonitions (`:::tip`, `:::warning`, `:::info`) are available for callout boxes
123+
124+
### Category Configuration
125+
126+
Each category has a `_category_.yml` file that controls its sidebar appearance:
127+
128+
```yaml
129+
position: 2 # Position in the sidebar
130+
label: Concepts # Display name
131+
collapsed: false # Whether the category starts collapsed
132+
link:
133+
type: generated-index
134+
title: Concepts Overview
135+
```
136+
137+
### Page Metadata
138+
139+
Pages can have front matter at the top to control their sidebar position and title:
140+
141+
```markdown
142+
---
143+
sidebar_position: 1
144+
sidebar_label: Custom Sidebar Label
145+
---
146+
147+
# Page Title
148+
```
149+
150+
### Docusaurus Features
151+
152+
This site uses [Docusaurus 3](https://docusaurus.io). Beyond standard Markdown, you can use:
153+
154+
- **Admonitions** for callout boxes: `:::tip`, `:::note`, `:::warning`, `:::danger`, `:::info`
155+
- **Code blocks** with syntax highlighting: ` ```python `, ` ```sh `, ` ```yaml `, etc.
156+
- **Tables**, **links**, and standard GFM (GitHub Flavored Markdown)
157+
158+
For more features, see the [Docusaurus documentation](https://docusaurus.io/docs).
159+
160+
---
161+
162+
## Style Guide
46163

47-
### Editing content
164+
When writing new pages, aim to match the existing style:
48165

49-
The actual content of the library is stored as markdown files within the `docs` directory.
50-
Each subdirectory of `docs` acts as a category, which then gets auto-generated into groups in the sidebar.
166+
- Write for undergraduate students — clear, direct language, no assumed expertise
167+
- Use second person ("you") to address the reader
168+
- Define terms before using them
169+
- Include practical examples and code snippets
170+
- Add a **References** section at the bottom with links to further reading
171+
- Use `:::tip` for helpful hints, `:::warning` for important cautions
51172

52-
For categories, the `_category_.yml` file may be used to modify a number of metadata options.
53-
Namely, the category's position within the sidebar with the `position` key, label with the `label` key, whether it starts collapsed with the `collapsed` key, and more.
173+
---
54174

55-
Each page also has metadata you can modify using the markdown file's [front matter](https://jekyllrb.com/docs/front-matter/).
56-
By default, the page title in the browser and sidebar will be taken from the first `h1` or `#` header on the page,
57-
these values can be modified with the `title` and `sidebar_label` keys respectively.
58-
A page's position on the sidebar can also be modified with the `sidebar_position` key, similar to how category positioning works.
175+
## License
59176

60-
That covers the basics of editing the ORL, but Docusaurus is an extensive tool with many so-far unused features.
61-
If you would like to learn more about Docusaurus and it's features, you can do so at the [Docusaurus docs](https://docusaurus.io/docs).
177+
See [LICENSE](LICENSE) for the license terms for this project's content.

0 commit comments

Comments
 (0)