Skip to main content
A site lives at the root of your repository, or in a folder you choose with Site is in a subdirectory (useful in monorepos, for example apps/blog), and every path on this page is relative to that folder.
Notra reads the files above, plus every .css file and every .js file outside blog/, changelog/, snippets/, public/ and slots/, wherever they are, and loads those on every page. Notra ignores other files, such as a README.md or a package.json. If the repository also holds your app’s code, put the site in its own folder and turn on Site is in a subdirectory.

​
blog.json is optional

Without a blog.json, the site builds with the standard layout and the site name from the dashboard, so add one when you want your own colors, logo, navigation, authors or analytics. See the blog.json reference. blog.json must sit at the root of the site folder, and the $schema line gives you autocomplete and inline errors in your editor:
blog.json

​
From file to URL

Every .md or .mdx file in blog/ and changelog/ becomes a page, and the path of the file becomes the URL below the section path:
  • File and folder names in blog/ and changelog/ may only use lowercase letters, digits and dashes, so My Post.mdx stops the build with slug_invalid.
  • Notra never publishes files and folders that start with _, so use them for notes or for MDX you import into other posts.
  • An MDX file that another file imports is a snippet rather than a page.
  • Two files can’t end up at the same URL, for example blog/launch.mdx and blog/launch/index.mdx.
Each section also gets an index page (/blog), an RSS feed (/blog/feed.xml), a sitemap (/blog/sitemap.xml), llms.txt and a Markdown version of every page. See AI agents and search.

​
Static files

Put images, videos, PDFs and fonts in public/ and reference them from the root of the site:
Notra rewrites the path at build time so it works under /blog, /changelog and on every domain, which puts the file public/images/editor.png at /blog/images/editor.png. Always use paths that start with /, because relative paths like ./editor.png don’t work.

​
Allowed files

Notra skips other files, dotfiles, node_modules and symbolic links, and file names may only use letters, digits, spaces and ._-@()+. For size limits, see Limits.
Last modified on October 8, 2026