How to Use ByteRun Website Compiler — A Step‑by‑Step GuideByteRun Website Compiler is a lightweight static site generator and build tool designed for speed, simplicity, and predictable output. This guide walks you through each step of using ByteRun — from installation and project setup to advanced workflows like asset optimization, templates, deployment, and troubleshooting. Whether you’re building a personal blog, documentation site, or marketing pages, this article will help you get the most from ByteRun.
What is ByteRun Website Compiler?
ByteRun is a compiler-oriented static site tool that converts source files (Markdown, templates, assets) into a static website. Unlike heavyweight frameworks, ByteRun focuses on minimal configuration, fast incremental builds, and producing deterministic output that’s easy to host anywhere. It supports features commonly needed by static sites: front matter, partials/includes, asset pipelines, and simple plugin hooks.
Key benefits
- Fast builds — optimized incremental compilation.
- Simple configuration — intuitive, limited options.
- Deterministic output — stable, cache-friendly files.
- Extensible — plugin hooks for custom steps.
Prerequisites
Before you start, ensure you have:
- Node.js (LTS recommended) or the ByteRun runtime (if distributed as a standalone binary).
- A code editor (VS Code, Sublime, etc.).
- Git (optional, but recommended for version control).
- Basic familiarity with Markdown and HTML.
Installation
ByteRun can be installed globally via npm (if distributed as a package) or downloaded as a platform binary. Below are typical installation steps using npm:
# Install globally npm install -g byterun-compiler # Or add to a project npm install --save-dev byterun-compiler If ByteRun provides a standalone binary, download the appropriate release from the official repository, make it executable, and add it to your PATH.
Creating a New Project
- Initialize a new project directory:
mkdir my-byterun-site cd my-byterun-site git init npm init -y - Generate a starter template (ByteRun may include a scaffold command):
byterun new # or npx byterun init This creates a standard structure:
- src/
- pages/
- templates/
- assets/
- byterun.config.js (or byterun.yml)
- package.json
Project Structure and Configuration
Typical directory layout:
- src/pages — Markdown or HTML pages with front matter.
- src/templates — Layout templates (e.g., Mustache, Nunjucks, or ByteRun’s template engine).
- src/partials — Reusable components (header, footer).
- src/assets — Images, CSS, JS.
- build/ — Generated site output.
Example byterun.config.js:
module.exports = { input: 'src', output: 'build', templateEngine: 'nunjucks', plugins: [ './plugins/optimize-images', './plugins/rss' ], dev: { port: 4000, liveReload: true } }; Configuration keys:
- input — source directory.
- output — compiled site directory.
- templateEngine — templating language.
- plugins — plugin paths or names.
- dev — development server options.
Writing Content
Create Markdown files in src/pages. ByteRun supports YAML front matter for metadata:
--- title: "Getting Started with ByteRun" date: "2025-08-31" tags: ["guide", "byterun"] --- # Welcome This is a ByteRun site page. Use Markdown to write content... Use templates to lay out pages. Example Nunjucks template (src/templates/base.njk):
<!doctype html> <html> <head> <meta charset="utf-8"> <title>{{ page.title }} - {{ site.title }}</title> <link rel="stylesheet" href="/assets/styles.css"> </head> <body> {% include 'partials/header.njk' %} <main>{{ content | safe }}</main> {% include 'partials/footer.njk' %} </body> </html> ByteRun will render Markdown content into the template, replacing placeholders like {{ content }} and exposing front matter as the page object.
Development Workflow
Start the dev server with live reload:
byterun dev # or via npm script npm run dev Dev features:
- Incremental builds — only changed files recompiled.
- Live reload — browser refresh on changes.
- File watching — rebuild when templates, pages, or assets change.
Use source maps for debugging CSS/JS during development.
Asset Pipeline
ByteRun can process and optimize assets during the build:
- CSS: support for PostCSS, autoprefixer, minification.
- JS: bundling via Rollup/ESBuild, transpilation, minification.
- Images: resizing, format conversion (AVIF/WebP), and compression.
Example plugin for images in byterun.config.js:
plugins: [ ['byterun-plugin-images', { formats: ['webp', 'avif'], quality: 80 }] ] Place assets in src/assets and reference them with absolute paths (e.g., /assets/image.jpg) or use helper tags that emit hashed filenames for cache-busting.
Templates and Partials
Use template features for DRY layouts:
- Partials: header, footer, nav.
- Layouts: default layout applied to pages automatically.
- Helpers/filters: custom functions for formatting dates, truncating text, etc.
Example helper registration (plugins/helpers.js):
module.exports = function registerHelpers(env) { env.addFilter('formatDate', (date) => new Date(date).toLocaleDateString()); }; Data Files and Collections
ByteRun supports global data files (JSON/YAML) and collections:
- data/site.yml — site-wide settings like title, baseUrl.
- collections — group pages by tag/type for index pages, feeds.
Example use: create src/data/site.yml:
title: "My ByteRun Site" baseUrl: "https://example.com" author: name: "Jane Doe" Use in templates as site.title, site.author.name, etc.
Building for Production
Run a production build:
byterun build # or npm run build Production mode typically:
- Minifies assets.
- Generates hashed filenames.
- Optimizes images.
- Produces sitemap.xml, robots.txt, RSS feeds (via plugins).
After build, the output is in the build/ directory ready to deploy.
Deployment
ByteRun output is static — deploy to any static host:
- GitHub Pages: push build/ to gh-pages branch.
- Netlify: connect repo and set build command to byterun build, publish directory build.
- Vercel: similar configuration; ensure static export.
- S3 + CloudFront: upload build/ contents to S3 bucket, configure CloudFront CDN.
Example Netlify settings:
- Build command: npm run build
- Publish directory: build
Plugins and Extensions
Extend ByteRun with plugins:
- Image optimization
- RSS generation
- Sitemap creation
- Search indexing (lunr/elasticlunr)
- Custom data sources (CMS, headless APIs)
Plugin API usually exposes lifecycle hooks: beforeBuild, afterBuild, onPageRender, onAssetCopy.
Testing and Quality Assurance
- Use link checkers to find broken links.
- Validate HTML/CSS with linters.
- Run accessibility audits (axe, Lighthouse).
- Add unit tests for custom plugins.
Troubleshooting
Common issues:
- Template errors — check syntax and helper registrations.
- Asset paths wrong — ensure baseUrl and asset helpers configured.
- Long build times — enable incremental builds and caching, audit plugins.
Logs and verbose mode help:
byterun build --verbose Example: Minimal Working Site
- Initialize project and config.
- Add src/pages/index.md with front matter.
- Add src/templates/base.njk and partials.
- Add an assets folder and a CSS file.
- Run byterun dev, then byterun build and deploy build/.
Conclusion
ByteRun Website Compiler provides a fast, predictable, and extensible static site workflow. Start small with a minimal site, then add plugins and optimizations as your needs grow. With its incremental builds and simple configuration, ByteRun is well-suited for both hobbyists and teams who want dependable static outputs.
Leave a Reply