Skip to content

Commit 41d8db8

Browse files
committed
Add Contributor Guide to provide instructions for contributing to the CMS User Guide
1 parent fa0b12e commit 41d8db8

5 files changed

Lines changed: 64 additions & 314 deletions

File tree

Globus_Guide.md

Lines changed: 0 additions & 22 deletions
This file was deleted.

Python_Starter_Guide_win64.md

Lines changed: 0 additions & 146 deletions
This file was deleted.

runXS_Starter_Guide_win64.md

Lines changed: 0 additions & 146 deletions
This file was deleted.

src/CONTRIBUTING.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Contributor Guide
2+
3+
Welcome! This guide explains how to contribute to the CMS User Guide using mdBook.
4+
5+
## How mdBook Works
6+
- All content lives in the `src/` directory as Markdown files.
7+
- The book structure is defined in `src/SUMMARY.md`.
8+
- When you push changes to the `main` branch, the book is automatically rebuilt and published to GitHub Pages.
9+
10+
## How to Add or Edit Content
11+
12+
### Add a New Chapter/Page
13+
1. Create a new Markdown file in `src/` (e.g., `src/New_Chapter.md`).
14+
2. Add a link to your new file in `src/SUMMARY.md`:
15+
```
16+
- [New Chapter](./New_Chapter.md)
17+
```
18+
3. Commit and push your changes to `main`.
19+
20+
### Edit Existing Content
21+
- Edit the relevant Markdown file in `src/`.
22+
- Commit and push your changes.
23+
24+
### Organize Chapters
25+
- Use `src/SUMMARY.md` to set the order and hierarchy of chapters.
26+
- Indent chapters under parents for nesting.
27+
28+
### Preview Locally (Optional)
29+
1. Install mdBook (if not already):
30+
- macOS: `brew install mdbook`
31+
- Linux: `cargo install mdbook`
32+
- Windows: Download from [mdBook releases](https://github.com/rust-lang/mdBook/releases)
33+
2. Run `mdbook serve` in the repo directory.
34+
3. Open `http://localhost:3000` in your browser.
35+
36+
## Best Practices
37+
- Always update `src/SUMMARY.md` when adding/removing/reordering chapters.
38+
- Use clear filenames and titles.
39+
- Preview locally before pushing.
40+
- Commit related changes together.
41+
42+
## Need Help?
43+
- Open an issue or ask in the repository discussions.
44+
45+
Thank you for contributing!
46+
47+
## Useful Links
48+
49+
- **Markdown Reference:**
50+
- [Markdown Guide (Comprehensive)](https://www.markdownguide.org/)
51+
- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
52+
- [mdBook User Guide](https://rust-lang.github.io/mdBook/)
53+
- **Markdown Editors:**
54+
- [Typora](https://typora.io/) — Live preview, cross-platform
55+
- [Mark Text](https://marktext.app/) — Free, open-source, cross-platform
56+
- [Obsidian](https://obsidian.md/) — Powerful knowledge base, free for personal use
57+
- [VS Code](https://code.visualstudio.com/) — With built-in Markdown preview
58+
- **Other Tools:**
59+
- [Dillinger](https://dillinger.io/) — Online Markdown editor
60+
- [StackEdit](https://stackedit.io/) — Online Markdown editor with cloud sync

src/SUMMARY.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,7 @@
88
- [Python Starter Guide](./Python_Starter_Guide_win64.md)
99
- [runXS.py Starter Guide](./runXS_Starter_Guide_win64.md)
1010
- [Beamline Quick Start Guide](./Beamline_Quick_Start.md)
11+
12+
# To Contributors
13+
14+
- [Contributor Guide](./CONTRIBUTING.md)

0 commit comments

Comments
 (0)