HSF Training SSH

An introduction to SSH. This repository holds the source code of the webpage that is rendered here. Contributions are welcome (see below)!

This training module is part of an initiative of the HEP Software foundation to build up a full software training curriculum for high energy physics.

Note: This repository has been converted from Jekyll/Carpentries to Jupyter Book.

🚀 Building the Book

Local Development

1. Install dependencies:

   pip install -r requirements.txt

2. Build the book:

   jupyter book build .

3. View the book: Open _build/html/index.html in your browser, or serve it locally:

   # Using Python's built-in server
   cd _build/html
   python -m http.server 8000

   Then navigate to http://localhost:8000

Clean Build

To clean previous builds and rebuild from scratch:

jupyter book clean .
jupyter book build .

📝 Content Structure

• intro.md: Landing page with prerequisites
• 01-introduction.md through 08-tips.md: Main lesson chapters
• setup.md: Setup instructions
• reference.md: Quick reference guide
• _config.yml: Jupyter Book configuration
• _toc.yml: Table of contents (defines chapter order)
• fig/: Images and figures

🤗 Contributing

We welcome all contributions to improve the lesson! Maintainers will do their best to help you if you have any questions, concerns, or experience any difficulties along the way.

If you make non-trivial changes (i.e., more than fixing a simple typo), you are eligible to be added to the HSF Training Community page, as well as to the list of contributors below.

Making Changes

1. Fork the repository and create a new branch
2. Edit the markdown files in the root directory (not in _episodes/ - those are archived)
3. Test your changes locally using the build instructions above
4. Commit your changes with a clear message
5. Submit a pull request to the jupyterbook branch

Pre-commit Hooks

Before committing, install the pre-commit hooks:

pip3 install pre-commit
pre-commit install

This will check for:

• Large files
• Merge conflicts
• Trailing whitespace
• Spelling errors (using codespell)

Writing Tips

• Use MyST Markdown syntax for admonitions, figures, and other rich content
• See the Jupyter Book documentation for formatting options
• Test locally before submitting a PR
• Use the existing chapters as examples for formatting

🚢 Deployment

The book is automatically built and deployed to GitHub Pages via GitHub Actions when changes are pushed to the jupyterbook branch. The workflow is defined in .github/workflows/deploy.yml.

📚 Jupyter Book vs Jekyll

This repository was previously built with Jekyll and the Carpentries template. It has been migrated to Jupyter Book for:

• Better support for modern web technologies
• More flexible content formatting with MyST Markdown
• Improved navigation and search
• Integration with Python/Jupyter ecosystem

Old Jekyll files are archived in _jekyll_archive/ for reference.

Authors

Thanks goes to these wonderful people (emoji key) who contributed to the content of the lesson:

Martin Ritter 🖋

Michael Eliachevitch 🖋

Kilian Lieret 🖋

936-BCruz 🖋

Even more people contributed to the framework, but they are too many to list!