Javelin is a powerful static site generator that allows you to create fast, modern, and highly customizable websites with ease. With its intuitive syntax, flexible templating system, and extensive plugin ecosystem, Javelin empowers developers to build beautiful and feature-rich websites quickly and efficiently. In this comprehensive guide, we'll walk you through the process of creating an example site with Javelin, covering everything from installation to deployment and beyond.

Introduction to Javelin

Javelin is a static site generator built with simplicity and performance in mind. It uses Markdown for content authoring and provides a powerful templating system based on Handlebars.js for building dynamic and reusable layouts. Javelin's modular architecture and plugin system make it easy to extend and customize, allowing developers to tailor their websites to meet specific requirements.

Key features of Javelin include:

  • Markdown Support: Write content in Markdown format, allowing for easy authoring and formatting.
  • Handlebars Templating: Use Handlebars.js templates to create dynamic layouts and reusable components.
  • Live Reload: Preview changes in real-time with Javelin's built-in live reload feature.
  • Asset Pipeline: Manage assets such as CSS, JavaScript, and images with Javelin's asset pipeline.
  • Extensible Plugin System: Extend Javelin's functionality with plugins for additional features and integrations.

Now, let's dive into the process of building an example site with Javelin.

Setting Up Your Environment

Before we can start building our example site with Javelin, we need to set up our development environment. Here's what you'll need:

  • Node.js and npm: Javelin is built with Node.js, so make sure you have Node.js and npm installed on your system.
  • Text Editor or IDE: Choose a text editor or integrated development environment (IDE) for writing code. Popular options include Visual Studio Code, Sublime Text, and Atom.
  • Terminal: You'll need a terminal or command prompt to run commands and interact with Javelin.

Once you have the necessary tools installed, you're ready to create your example site with Javelin.

Creating a New Javelin Project

To create a new Javelin project, use the Javelin CLI (Command Line Interface) to initialize a new project directory. Open your terminal and run the following command:

npx javelin-cli init my-example-site

This command will create a new directory named my-example-site and initialize a new Javelin project inside it. Follow the prompts to configure your project settings, such as the site name, author name, and default layout.

Writing Content with Markdown

With your Javelin project initialized, you can start writing content for your example site using Markdown. Create a new Markdown file inside the content directory to represent each page of your site. For example, you might create a home.md file for the homepage and additional files for other pages such as about.md, blog.md, and contact.md.

Here's an example of a basic Markdown file for the homepage:

---
title: Home
---

# Welcome to My Example Site!

This is the homepage of my example site. Feel free to explore and learn more about what we have to offer.

Javelin uses front matter (YAML or JSON metadata at the top of each Markdown file) to define metadata such as the page title, layout, and any custom variables or options.

Creating Layouts with Handlebars

Next, let's create a layout template using Handlebars.js to define the structure and styling of our example site. Layouts are reusable templates that define the overall structure of a web page, including common elements such as headers, footers, and navigation menus.

Create a new file named default.hbs inside the layouts directory to serve as the default layout template for your example site. Here's a simple example of a default layout template:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title></title>
</head>
<body>
    <header>
        <h1></h1>
        <nav>
            <ul>
                <li><a href="/">Home</a></li>
                <li><a href="/about">About</a></li>
                <li><a href="/blog">Blog</a></li>
                <li><a href="/contact">Contact</a></li>
            </ul>
        </nav>
    </header>
    <main>
        }
    </main>
    <footer>
        &copy;  
    </footer>
</body>
</html>

In this layout template, we use Handlebars expressions , , , and to dynamically insert content and metadata into the HTML structure. The } expression is a Handlebars "triple-stash" that renders the actual content of each page.

Styling with CSS

With our content and layout in place, let's add some styling to our example site using CSS. Create a new CSS file named styles.css inside the assets/css directory to define the styles for your site.

Here's a basic example of a CSS file to style our example site:

/* styles.css */

body {
    font-family: Arial, sans-serif;
    margin: 0;
    padding: 0;
}

header {
    background-color: #333;
    color: #fff;
    padding: 1rem;
}

nav ul {
    list-style: none;
    padding: 0;
}

nav ul li {
    display: inline;
    margin-right: 1rem;
}

main {
    padding: 2rem;
}

footer {
    background-color: #333;
    color: #fff;
    padding: 1rem;
    text-align: center;
}

Feel free to customize the styles according to your preferences and design requirements.

Building and Previewing Your Site

Now that we have our content, layout, and styling in place, let's build our example site with Javelin and preview it in the browser. Open your terminal and navigate to your project directory, then run the following command:

npx javelin-cli build

This command will compile your Markdown content, apply your layout templates, and generate a static HTML site in the dist directory.

To preview your site locally, you can use Javelin's built-in development server. Run the following command in your terminal:


npx javelin-cli serve

This command will start a local web server and open your site in your default web browser. You can now navigate to http://localhost:3000 to view your example site.

Customizing and Extending Your Site

Now that you have a basic example site up and running with Javelin, the possibilities for customization and extension are endless. Here are a few ideas to further customize and extend your example site:

  • Add Additional Pages: Create additional Markdown files for different sections or pages of your site.
  • Integrate Plugins: Explore Javelin's plugin ecosystem to add features such as syntax highlighting, SEO optimization, or analytics tracking.
  • Customize Layouts: Experiment with different layout templates and styles to give your site a unique look and feel.
  • Optimize Performance: Optimize your site for performance by minifying CSS and JavaScript, optimizing images, and leveraging caching techniques.

Deploying Your Site

Once you're satisfied with your example site, it's time to deploy it to a web server so that others can access it. There are many ways to deploy a static site like the one we've created with Javelin, including:

  • Manual Deployment: Upload the contents of the dist directory to a web server using FTP or a file manager.
  • CI/CD Pipeline: Set up a continuous integration and continuous deployment (CI/CD) pipeline to automate the deployment process.
  • Static Site Hosting: Use a static site hosting service such as Netlify, Vercel, or GitHub Pages to deploy your site with ease.

Choose the deployment method that best suits your needs and preferences, and share your example site with the world!

Exporting Your Site as Jar

To export your example Javelin site as a JAR (Java Archive) file, you can use Javelin's built-in functionality to package your static site into a self-contained executable JAR file. This allows you to distribute your site as a single file that can be run on any system with Java installed. Here's how you can do it:

  1. Build Your Javelin Site: First, ensure that you have built your Javelin site using the javelin-cli build command. This command generates the static HTML files for your site in the dist directory.
  2. Create a Manifest File: In order to package your site as a JAR file, you need to create a manifest file (manifest.txt) that specifies the main class to be executed when the JAR file is run. Create a file named manifest.txt in your project directory with the following content: 
    Main-Class: com.example.Main

    Replace com.example.Main with the fully qualified name of the main class for your Javelin site. This class should contain the main method that initializes and runs your Javelin site.

  3. Package Your Site as a JAR File: Once you have created the manifest file, you can use the jar command provided by the Java Development Kit (JDK) to package your site into a JAR file. Open a terminal or command prompt, navigate to your project directory, and run the following command: 
    jar cfm my-site.jar manifest.txt -C dist .

    This command creates a JAR file named my-site.jar using the manifest file manifest.txt and includes all the files and directories in the dist directory.

  4. Test Your JAR File: Once the JAR file is created, you can test it by running it with the java command. Navigate to the directory containing the JAR file in your terminal or command prompt, and run the following command: 
    java -jar my-site.jar

    This command will execute the JAR file, launching your Javelin site in a local web server. You can then access your site by navigating to http://localhost:3000 in your web browser.

  5. Distribute Your JAR File: Finally, once you have tested your JAR file and verified that your site is working correctly, you can distribute the JAR file to others. They can run your site on their own systems by simply executing the JAR file with the java -jar command.

By following these steps, you can export your example Javelin site as a JAR file and distribute it as a self-contained executable, making it easy for others to run your site locally without having to set up a web server or install additional dependencies.

Conclusion

In this comprehensive guide, we've covered everything you need to know to create an example site with Javelin. From setting up your development environment to writing content, creating layouts, styling with CSS, and deploying your site, you now have the knowledge and tools to build beautiful and functional websites with Javelin.

Whether you're building a personal blog, portfolio, documentation site, or e-commerce store, Javelin provides the flexibility and power you need to bring your vision to life. With its intuitive syntax, powerful templating system, and extensive plugin ecosystem, Javelin empowers you to create modern and highly customizable websites quickly and efficiently.

So why wait? Start building your next project with Javelin today and unleash your creativity on the web!