Installing and Configuring Jigsaw in the ServBay Environment

Overview

This document is designed to guide you through installing and configuring the Jigsaw static site generator within ServBay, a powerful local web development environment. ServBay offers an integrated stack for PHP, Node.js, and more, greatly simplifying the process of setting up Jigsaw projects. With ServBay, you can easily configure local domains, HTTPS, and efficient web servers for your Jigsaw projects, allowing you to focus on website content development.

What is Jigsaw?

Jigsaw is a static site generator built with Laravel components, developed by Tighten. It leverages the power and flexibility of the Laravel Blade templating engine, combined with Markdown files, to generate pure static HTML websites. Jigsaw is ideal for documentation sites, blogs, landing pages, or any site that doesn't require a backend database or dynamic server processing. Its core advantages include:

• Familiar tools: If you're already comfortable with Laravel or Blade, you'll find Jigsaw easy to pick up.
• Performance and security: The generated static sites load extremely fast, and without server-side code execution, security risks are minimized.
• Flexible templates: Build sophisticated layouts and components using Blade templates.
• Markdown support: Effortlessly write content.

Use Cases

Jigsaw is well-suited for the following scenarios:

• Project documentation and API documentation sites
• Personal blogs or tech sharing websites
• Corporate or product landing pages
• Small showcase or portfolio sites
• Any content-focused website that requires high performance and security

Prerequisites

Before you begin, please ensure you meet the following requirements:

1. ServBay is installed and running: You need to install and launch ServBay on macOS. ServBay comes bundled with PHP, Composer, and Node.js/npm, all of which are required for installing and running Jigsaw.
2. Basic command line knowledge: You should be comfortable using the terminal to execute commands.
3. Familiarity with Composer and npm: Installing Jigsaw requires Composer, and frontend asset compilation depends on npm.

Installation and Configuration Steps

This section provides detailed instructions on how to install and configure a Jigsaw project within the ServBay environment.

Step 1: Create the Project Directory

First, open your terminal application, navigate to the ServBay recommended web root /Applications/ServBay/www, and create a subdirectory for your Jigsaw project.

cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

We've named the project directory servbay-jigsaw-demo; all project files will be stored here.

Step 2: Create a Jigsaw Project Using Composer

ServBay comes pre-installed and configured with Composer, so you can use the composer command directly in any terminal window. Now, in the project directory you just created (/Applications/ServBay/www/servbay-jigsaw-demo), run the following Composer command to create your Jigsaw project:

composer create-project tightenco/jigsaw .

This command downloads the latest version of Jigsaw along with all PHP dependencies into the current directory (.). Please note that the . at the end means the project is created within the current directory rather than inside a subfolder named jigsaw.

Step 3: Configure the Website in ServBay

To access your Jigsaw website via a web browser, you'll need to configure a local site for this project within ServBay.

1. Open the ServBay UI: Double-click the ServBay application icon or open the ServBay control panel via the menu bar icon.
2. Go to "Sites": Click the "Sites" tab in the left navigation panel.
3. Add a New Site: At the bottom of the interface, click the "+" button and select "Add Site".
4. Fill In Site Details:
   • Name: Enter a recognizable name, such as ServBay Jigsaw Demo.
   • Domain: Type the domain you'd like to use for local access. It's recommended to use a .servbay.demo suffix to avoid clashing with real domains, e.g., jigsaw-demo.servbay.demo. ServBay will automatically map .servbay.demo domains to your local machine.
   • Site Type: Select PHP, since Jigsaw's build process requires a PHP environment.
   • PHP Version: Choose one of the installed PHP versions within ServBay; a recent stable version is recommended.
   • Site Root: This is a crucial step. By default, Jigsaw's generated static files are located in the build_local directory at the root of your project. Set the site root to point to this build output directory: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. Save and Apply: After filling in all the details, click "Save". ServBay will prompt you to apply changes; confirm this. ServBay will automatically update the web server configuration (Caddy or Nginx) and set up HTTPS for you.

Step 4: Install Frontend Dependencies

Jigsaw projects typically use npm to manage and compile frontend assets such as SASS and JavaScript files. Node.js and npm are also built into ServBay.

Within your project directory (/Applications/ServBay/www/servbay-jigsaw-demo), run the following command to install frontend dependencies:

npm install

This reads the package.json file at the project root and downloads the necessary Node.js modules into the node_modules directory.

Step 5: Build the Jigsaw Site

Once all dependencies are installed, run the Jigsaw build command to generate the static site files.

In your project directory, execute:

./vendor/bin/jigsaw build

This command will:

1. Process Markdown files and Blade templates within the source directory.
2. Run the compilation tasks defined in webpack.mix.js (if Laravel Mix was included via npm install).
3. Output the final static HTML, CSS, JS, and other assets into the build_local directory.

Step 6: Visit Your Website

The static files for your Jigsaw site are now generated in the /Applications/ServBay/www/servbay-jigsaw-demo/build_local directory. Because you set the site root to here in ServBay, you can now access your site using your browser.

Open your web browser and visit the domain you configured in Step 3, for example, https://jigsaw-demo.servbay.demo. ServBay handles local HTTPS certificates automatically (using its own ServBay User CA), and you should see Jigsaw's default welcome page.

Customization and Development

Now that you have your basic environment set up, you can begin customizing the content and styles of your Jigsaw site.

Editing Content and Templates

• The source code for your site resides in the source directory at your project root.
• HTML layouts and components use Blade templates, located in subdirectories such as source/_layouts and source/_partials.
• Page content is typically written in Markdown, located in the source directory or its subdirectories (for example, source/index.md, source/about.md).
• Blog posts are usually found in the source/_posts directory, following the naming format YYYY-MM-DD-slug.md.

Adding New Pages or Posts

To add a new page or blog post, just create a new Markdown file in the source directory or an appropriate subdirectory (such as source/_posts).

For example, create a source/about.md file:

---
title: "About Us"
description: "Learn more about ServBay Jigsaw Demo"
---

# About Us

This is an about page built with Jigsaw.

Here you can add company introductions, team information, and more.

Customizing Styles and Scripts

Jigsaw projects typically use Laravel Mix (webpack.mix.js) for frontend asset compilation.

• Stylesheets (often SASS/SCSS) are stored in the source/_assets/sass directory.
• JavaScript files are stored in source/_assets/js.

In your project directory, use npm scripts to compile these assets:

• npm run dev: Compile assets for development; usually includes source maps and is unminified.
• npm run watch: Compile assets for development and automatically rebuild on file changes—particularly useful during active development.
• npm run prod: Compile production-ready assets, including minification and optimizations.

For example, after editing source/_assets/sass/main.scss, run npm run dev or npm run watch to update the corresponding CSS file.

Rebuilding the Site

Important: Whenever you make changes to content files (Markdown) or template files (Blade) in the source directory, you must rerun the Jigsaw build command so Jigsaw can process the changes and update the static files in build_local:

./vendor/bin/jigsaw build

If you've made changes to frontend asset files (SASS, JS), you need to run npm run dev or npm run watch to recompile those assets. In most Jigsaw projects, the Jigsaw build command will also trigger Mix's compilation process, but keeping them separate helps during debugging.

Notes

• Build output directory: By default, Jigsaw outputs to build_local (development) and build_production (production). Make sure your ServBay site root is set to the directory you want to serve (typically build_local for local development).
• Web server: ServBay uses Caddy or Nginx as its web server, which serves static files directly from the build_local directory for high efficiency. You do not need to use Jigsaw's built-in jigsaw serve command (which is mainly for quick previews and is less feature-rich than ServBay's full web server).
• HTTPS: ServBay auto-configures HTTPS for .servbay.demo domains and uses its own ServBay User CA to sign certificates. You may need to trust the ServBay User CA certificate in your system to avoid browser warnings.
• Clean builds: If you encounter odd build issues, try running ./vendor/bin/jigsaw build --clean for a clean rebuild.

Frequently Asked Questions (FAQ)

Q: I edited a Markdown file, but I don't see the update in my browser?

A: After modifying content or templates, you need to rerun ./vendor/bin/jigsaw build in your terminal to rebuild the site.

Q: I changed a SCSS file, but the styles aren't updating?

A: After changing frontend asset files, run npm run dev or npm run watch in your project directory to recompile the assets.

Q: Why do I get 'Site can't be reached' or 'File not found' when accessing my local domain?

A: Please check the following:

1. Confirm that ServBay is running.
2. In ServBay's configuration for your site: Is the domain correct? Is the site root pointing to /Applications/ServBay/www/servbay-jigsaw-demo/build_local?
3. Have you successfully run ./vendor/bin/jigsaw build? Are static files such as index.html present in the build_local directory?

Q: How do I deploy a Jigsaw site?

A: Jigsaw outputs pure static files. The typical process is:

1. Run ./vendor/bin/jigsaw build production to generate a production build (usually with further optimizations).
2. Upload all files from the build_production directory to any static site hosting provider (such as Netlify, Vercel, GitHub Pages, various cloud storage services, etc.).

Conclusion

Thanks to ServBay, installing and configuring the Jigsaw static site generator on macOS is both efficient and convenient. ServBay provides all necessary runtime environments (PHP, Composer, Node.js, npm) and powerful local web server configuration. By following this guide, you can quickly launch a Jigsaw project and take full advantage of ServBay's features to streamline your local development workflow.