Preview a repository's docs

epresso docs renders a directory of Markdown as a documentation site and — when that directory is a git checkout — links every page back to its repository. No site.toml required.

Render a repo's docs

Point it at a local clone, or give it the repository directly:

  


    
        
    
    
    
        
            
                bash
            
        
        
        
    







  
epresso docs ../my-repo                  # a local checkoutepresso docs github:owner/repo@v1        # clone + render (branch, tag, or commit-ish)epresso docs https://github.com/owner/repo

A git source is shallow-cloned into .cache/repos/ and reused on later runs (epresso clean clears it). Because the clone keeps its .git, the pages link back to the repository — see below.

epresso copies the bundled docs theme into a temporary project, injects the Markdown as its docs collection, and serves the result on http://127.0.0.1:4321. The sidebar tree, search index, and on-page table of contents are all built from the Markdown itself.

For a git checkout, epresso copies the markdown under the docs directory (default docs/, overridable with EPRESSO_DOCS_DIR or REPO_DOCS) plus a top-level README, and skips build junk. A bare Markdown directory is copied whole.

When the source is a git checkout, epresso reads its origin remote and default branch and writes them into the generated project's site.toml:

  


    
        
    
    
    
        
            
                toml
            
        
        
        
    







  
[site]repository = "https://github.com/you/my-repo"branch = "main"

Those two fields drive the view / edit this source links on every page, so the preview points at the real repository rather than the theme's own. The source path is recorded as docs_source, and the collection it populates as [theme] docs_base — see Configuration for those fields.

If the directory you pass already has its own site.toml, epresso builds it as-is and its own [site] repository / branch decide the links.

Use your own theme

--theme replaces the bundled docs theme:

  


    
        
    
    
    
        
            
                bash
            
        
        
        
    







  
epresso docs ../my-repo --theme ../my-theme

The theme project is copied and re-pointed at your Markdown, so any docs theme works — see Create a theme.

Write a static build

--out skips the server and writes a production build — useful for CI:

  


    
        
    
    
    
        
            
                bash
            
        
        
        
    







  
epresso docs ../my-repo --out dist/docs

The output is an ordinary static site; deploy dist/docs/ anywhere. For a project that already has its own site.toml, epresso build is the direct route.

Branding

If the source directory contains logo.svg, favicon.ico, or styles.css (style.css also works), they are picked up and applied to the rendered docs: the favicon and header logo are replaced, and the stylesheet is appended to the theme's global CSS so its variable overrides win.

Next