LearnaOS

Any repo. One command. Your personal learning OS.

Turn any GitHub repo or local folder into a clean, readable HTML site that handles markdown, Jupyter notebooks, code files, CSV data, and images correctly. No config files, no broken links, no 404s.

npx learnaos ./mlops-zoomcamp
# ➜ http://localhost:4040

That is the whole setup. Point it at a folder, and it builds a navigable site, serves it locally, and rebuilds as you edit.

Why it exists

Most course content on GitHub is great but painful to read as raw markdown, and the common viewers each fall short somewhere:

| Tool | The catch | | ----------- | ------------------------------------------------------ | | Docsify | Breaks on folders, notebooks, code files, image paths | | Jupyter Book | Notebook-focused, slower builds, needs config | | MkDocs | Needs mkdocs.yml and per-repo setup | | Sphinx | Powerful but complex, Python-only | | LearnaOS | One command, zero config, reads everything in the repo |

LearnaOS is a reader, not a runtime. It never executes your code, so it stays fast and predictable. It also never edits your source files. Everything is generated into a separate output folder.

What it handles

• Markdown (.md) — rendered with syntax-highlighted code and heading anchors.
• Jupyter notebooks (.ipynb) — markdown cells, code cells, stream output, errors, HTML output, and embedded images all render inline.
• Code files (.py, .js, .ts, .go, .rs, and many more) — full syntax highlighting with a line gutter.
• Data (.csv, .tsv) — parsed into sortable, scrollable tables.
• Images — referenced images resolve correctly, and folders of images get a gallery.

The hard part most tools get wrong is links. LearnaOS resolves every internal link and image against the real file tree and rewrites it to a correct relative path, so the site works whether you open it locally, host it in a subfolder, or deploy it to a CDN. Folder links, ../ cross-module links, and root-absolute /path links all resolve.

Usage

# Serve a local folder with live rebuild
learnaos ./course-notes

# Pull a repo straight from GitHub (requires git)
learnaos DataTalksClub/mlops-zoomcamp

# Build a static site and host it anywhere free
learnaos ./course-notes --export --out site

Options

| Flag | Description | | ----------------- | ---------------------------------------- | | -e, --export | Build a static site and exit | | -o, --out <dir> | Output folder (default ./learnaos-site) | | -p, --port <n> | Dev server port (default 4040) | | -n, --name <s> | Override the site name | | -h, --help | Show help | | -v, --version | Show version |

Hosting for free

--export produces a self-contained folder of plain HTML, CSS, and JS. Drag it into GitHub Pages, Netlify, or Vercel and it just works. No server required.

How it works

1. Scan the folder into a sorted tree, classifying every file by type and skipping noise like node_modules and .git.
2. Resolve landing pages so each folder opens to its README.md, or an auto-generated index when there is none.
3. Render each file with the right renderer and rewrite internal links to correct relative output paths.
4. Copy images and assets, then drop in the theme.

Contributing

LearnaOS is open source under MIT, and contributions of every size are welcome, from a typo fix to a whole new renderer. The first thing to do is try it on a real repo and tell us where it fell short. See CONTRIBUTING.md for the local setup and the project map.

License

MIT. See LICENSE.