Last updated: settembre 2025

Installation Guide

This guide will help you install and set up Neutrino, a privacy-first static site boilerplate built with Eleventy and Decap CMS.

Prerequisites

Before installing Neutrino, ensure you have the following installed on your system:

Node.js (version 18 or higher)
npm (comes with Node.js)
Git (for version control)

Checking Prerequisites

Verify your installations:

node --version
npm --version
git --version

Installation Methods

Method 1: Clone from Repository

Clone the repository:

git clone https://github.com/greenpandastudio/neutrino-electron.git
cd neutrino-electron

Install dependencies:
Terminal window
```
npm install
```

Method 2: Download and Extract

Download the latest release from the GitHub repository
Extract the archive to your desired location
Navigate to the project directory
Run npm install

Environment Configuration

Setting Up Content Directory

Neutrino supports external content management through environment variables:

Create a .env file in the project root:
Terminal window
```
touch .env
```
Configure the content path in your .env file:
Terminal window
```
NEUTRINO_CONTENT_PATH=/path/to/your/content/directory
```
If you don't set this variable, Neutrino will use the default content directory.
Alternative: Edit site.json

You can also configure the content path directly in src/_data/site.json:
```
{
  "contentPath": "/absolute/path/to/your/content"
}
```

Theme Configuration

Set your preferred theme using the THEME environment variable:

THEME=neutrino-electron-core

Available themes:

neutrino-electron-core (default)
neutrino-brand-website

Development Setup

1. Start Development Server

Run the development server with CSS watching:

npm run serve

This command will:

Start Eleventy in serve mode
Watch for CSS changes and recompile automatically
Serve your site at http://localhost:8080

2. Alternative Development Commands

Development without CSS watching:
Terminal window
```
npm run dev
```
CSS-only watching:
Terminal window
```
npm run watch:css
```
Build CSS only:
Terminal window
```
npm run build:css
```

Building for Production

Build the Site

Generate the production build:

npm run build

This will:

Compile all SCSS to CSS
Process all templates and content
Generate the static site in the _site directory

Build Output

The built site will be available in the _site directory, ready for deployment to any static hosting service.

Content Management

Using Decap CMS

Access the admin panel: Navigate to http://localhost:8080/admin in your browser
Configure authentication: Follow the Decap CMS documentation to set up authentication for your chosen backend
Content structure:
- Posts: src/content/posts/
- Pages: src/content/pages/
- Projects: src/content/projects/
- Documentation: src/content/documentation/

Manual Content Management

You can also manage content manually by editing Markdown files in the appropriate directories.

Troubleshooting

Common Issues

Content directory not found:
- Verify the path in your .env file or site.json
- Ensure the directory exists and is accessible
CSS not compiling:
- Check that all SCSS files are valid
- Ensure the theme directory exists
Port already in use:
- Eleventy will automatically find an available port
- Check the terminal output for the actual URL

Getting Help

Check the troubleshooting guide
Review the configuration documentation
Open an issue on the GitHub repository

Next Steps

After successful installation:

Read the configuration guide
Explore the theme system
Set up content management
Learn about deployment options

System Requirements

Node.js: 18.0.0 or higher
npm: 8.0.0 or higher
Memory: 512MB RAM minimum
Disk Space: 100MB for the project, additional space for content

Key Dependencies

Neutrino uses modern, well-maintained dependencies:

Eleventy: 3.0+ (Static site generator)
Decap CMS: Latest (Headless CMS)
Sass: 1.79+ (CSS preprocessor)
Expressive Code: 0.41+ (Syntax highlighting)
Markdown-it: 14.1+ (Markdown processor)

Supported Platforms

Windows 10/11
macOS 10.15+
Linux (any distribution with Node.js 18+)