Start from a template

Scaffold a full site from a ready-made theme with epresso new.

epresso new scaffolds a project from a starter template or a theme — a complete, runnable site — into a new directory, and strips its git history. You own the result outright.

Run it with no arguments for an interactive prompt:

  


    
        
    
    
    
        
            
                bash
            
        
        
        
    







  
epresso new


  


    
        
    
    
    
        
        
        
    







  
Where should we create your new project?.How would you like to start your new project?  1. A basic, helpful starter project (recommended)  2. Use the blog template  3. Use the docs template  4. Use the minimal (empty) template
Template What you get
basic Directories, site.toml, a page, a Base layout and content.config.py
docs The documentation theme (ships with epresso under themes/)
blog The blog theme
minimal site.toml + one bare page — nothing else

Skip the prompts by passing the template and destination, or -y for the basic starter in the current directory:

  


    
        
    
    
    
        
            
                bash
            
        
        
        
    







  
epresso new docs mysite     # a documentation siteepresso new minimal mysite  # the smallest buildable projectepresso new -y              # basic starter, current directorycd mysite && epresso dev

A theme can also be a git source or a local directory — useful while a theme has no registry entry yet:

  


    
        
    
    
    
        
            
                bash
            
        
        
        
    







  
epresso new github:nikoshell/epresso-theme-docs mysiteepresso new ./epresso-theme-mytheme mysite

See the available names:

  


    
        
    
    
    
        
            
                bash
            
        
        
        
    







  
epresso new --help          # Template (basic, blog, docs, minimal) …

What you get

The scaffold is a normal epresso project, so everything in Create a new website applies. A docs theme, for example, ships far more than the blank scaffold:

  


    
        
    
    
    
        
            
                tree
            
        
        
        
    







  
mysite/  site.toml  content.config.py  pages/                      # routes, including dynamic ones  layouts/                    # DocsBase.ep, DocsPage.ep — the page shells  components/    primitives/               # DocsIcon, DocsIconButton    controls/                 # DocsPager, DocsSearchButton, …    navigation/               # DocsBreadcrumbs, DocsNavAccordion, DocsToc    patterns/                 # DocsMarkdown, DocsHighlight, DocsCodeHead, …    structure/                # DocsHeader, DocsFooter  styles/                     # docs.css: design tokens + base styles  public/                     # favicon, etc.

Build and preview it as production:

  


    
        
    
    
    
        
            
                bash
            
        
        
        
    







  
epresso buildepresso preview

Customizing a template

You are editing a copy, so change anything:

  1. Identify it — site.toml: [site] name, url, repository, branch.
  2. Adjust the shell — layouts/DocsBase.ep (the whole document) and layouts/DocsPage.ep (the documentation page frame).
  3. Restyle — styles/ holds the tokens and global CSS. [assets] css names the entry point.
  4. Delete what you don't need — demo pages under pages/, unused components. Nothing else depends on them.
  5. Add your content — drop Markdown into content/ and point a collection at it in content.config.py.

Because it is a copy, upstream theme changes are not picked up. If you want to keep receiving updates while overriding only some files, that is the planned layer mode — a Coming soon tutorial, visible in local previews.

How epresso new fetches a theme

<theme> is one of three things:

Form Example
A registry name docs, blog
A git URL github:owner/repo, https://github.com/owner/repo.git, git@github.com:owner/repo.git
A local directory ./epresso-theme-mytheme, ~/themes/blog

Add @ref to a git source to pick a branch or tag:

  


    
        
    
    
    
        
            
                bash
            
        
        
        
    







  
epresso new github:nikoshell/epresso-theme-docs mysiteepresso new github:nikoshell/epresso-theme-docs@v1 mysite     # pinned to a tagepresso new git@github.com:nikoshell/epresso-theme-docs.git mysiteepresso new ./epresso-theme-mytheme mysite

Resolution is: a local directory is copied (git history stripped); anything else is git clone --depth=1 <repo> <dest>, with --branch <ref> added only when a ref is given — so a plain URL uses the repository's default branch.

A registry name maps to a repository in src/epresso/themes.py, and is the only form that can additionally fall back to a bundled starter inside epresso:

  


    
        
    
    
    
        
            
                python
            
        
        
        
    







  
REGISTRY = {    "docs": ("<repo>/themes/docs", "main"),          # ships in this repository    "blog": ("...epresso-theme-blog", "main"),         # sibling checkout / git URL}

docs ships with epresso under themes/, so epresso new docs copies it directly — no clone and no network. Other names resolve to a local path to a sibling checkout while developing, or a published git URL.

The docs theme specialises in rendering an existing Markdown tree (it is what builds these pages), so a scaffolded copy points at its enclosing repository via [theme] repo / [theme] docs_dir in site.toml. After epresso new docs mysite, set those to your repository and docs folder — or replace them with your own pages — before building.

Next steps