LearnOSM is the open-source Jekyll repository behind learnosm.org, a community-maintained site dedicated to teaching people how to map in OpenStreetMap (OSM) and use the OSM community's software and tools.
What is LearnOSM?
LearnOSM is the GitHub repository that stores the content, Jekyll layouts, and issue tracking for https://learnosm.org. The repository's content is written in Markdown and organized in the _posts directory, and the site is built with Jekyll. Any update pushed to the gh-pages branch automatically publishes to the live site within minutes, so contributions go live quickly.
The repository is maintained by the Humanitarian OpenStreetMap Team (HOT), as indicated by the contact email [email protected]. Its purpose is educational: it helps beginners and intermediate users learn how to contribute to OpenStreetMap and get familiar with the mapping tools used in the community.
Key Features
- Jekyll layouts and content — the repository contains both the Markdown posts and the Jekyll templates that render learnosm.org, so the whole site is version-controlled.
- Automatic deploy via GitHub Pages — commits to the
gh-pagesbranch trigger a site update within minutes; there is no manual build or deployment step. - Simple editing for minor fixes — anyone can fix typos, grammar, and small issues in English documents directly through GitHub's "edit this file" feature, no clone or pull request needed.
- Coordinated reworks — for larger changes like rewriting a document, modifying images, or submitting a new document, contributors are asked to contact [email protected] first to coordinate.
- Translation managed through Transifex — translations are not accepted as pull requests; instead, translators use the workflow at /en/contribute/translator/ so that translated content is managed separately.
- Public issue tracking — the repository doubles as the site's issue tracker, making bugs, content gaps, and suggestions visible and actionable.
Who should use LearnOSM?
LearnOSM is built for people who want to learn or teach OpenStreetMap. New mappers can read the guides to understand how to contribute map data, while experienced mappers can reuse the material for training sessions. Translation volunteers have a clear channel to localize the documentation, and educators can use the open Jekyll structure as a model for their own mapping tutorials.
What can you do with LearnOSM?
- Aspiring OSM contributors: follow the tutorials to learn the concepts and practice editing OpenStreetMap.
- Community trainers: point newcomers to specific posts in the
_postsdirectory as homework or in-class exercises. - Open-source contributors: submit small English fixes via GitHub's edit feature, or request larger changes by emailing the team.
- Site maintainers: deploy updates by pushing to the
gh-pagesbranch, and manage translations through the Transifex workflow.
How does LearnOSM work?
The site is a Jekyll static site hosted on GitHub Pages. Content lives as Markdown files in the _posts directory, and the Jekyll layouts in the repository turn those files into HTML. When a contributor updates a file and a change lands on the gh-pages branch, GitHub rebuilds the site and the changes appear on learnosm.org within minutes. For translations, contributors use Transifex, which then integrates with the repository rather than having translated files merged directly.
