Getting Started: Working With Content

This is part 1 of the 3-part Getting Started Guide. This page shows you how to build a basic site with JS.SSG. It covers how to prepare your content in Markdown files, and how to use JS.SSG to convert those Markdown files into production-ready HTML.

Part 2 covers working with templates and part 3 covers working with assets.

  1. Overview
  2. Preparing Your Content
  3. Installing JS.SSG
  4. Building Your Site


At its most basic, JS.SSG is a tool for converting your markdown files into HTML that you can use to build a website. In order to have full control over the final site, you'll need three things:

  1. Content (a website without content is nothing)
  2. Templates (a way to choose how to display you content)
  3. Assets (styles and scripts and images to enhance how your content is displayed)

JS.SSG helps with all of those things, but it's so simple that you can just start with content and nothing else.

This page will focus on how to prepare your content for JS.SSG, and how to then use JS.SSG to convert that content into HTML pages that can be deplpoyed as a website.

the content aspect of building your website with JS.SSG, but it's important to note that templates and assets are also important for creating a complete and functional website.

Preparing Your Content

Your content needs to be written in Markdown or MDX files (.md or .mdx). Each file must include a "title" value in the frontmatter (e.g. "title: My First Blog Post"). These content files can be used to create the pages of your website.

What is Markdown

Markdown is a lightweight markup language that you can use to add formatting to plain text documents. It was created to be easy to read and easy to write, and it can be converted seamlessly to many other formats.

Example files

A content file should look something like this:

title: My First Blog Post

Welcome to my first blog post! This is a placeholder post that I've created to demonstrate the structure of a markdown file.

I can write as much or as little as I want here. I can use markdown formatting to make my text bold, italic, or create links.

For example, I can make this word **bold** or this word *italic*. I can also create a [link to Google]( or a [link to my blog's homepage](/).

## Conclusion

This is the end of my blog post. Thanks for reading!

And your project's folder should look something like this:

├── content/
|   ├── blog/
|   |   ├── my-first-blog-post.mdx
|   |   └── my-second-blog-post.mdx
|   ├── about.mdx
|   ├── contact.mdx
|   └── index.mdx
└── package.json

Why do you need a package.json file?

The package.json file is required because JS.SSG is a node module. It stores information about the dependencies for your project, as well as metadata like the title and version.

Installing JS.SSG

Install JS.SSG using Yarn with the following command:

yarn add jsssg

You can also use npm install jsssg if you prefer NPM.

Building Your Site

You are now ready to build your site. Do this by running

yarn jsssg

This will create a build/ folder in the root of your project. It will contain all the files for your new website. Every markdown file in your content/ folder will be converted into an HTML file in the build/ folder.

Your folder structure will now look like this:

├── build/
|   ├── blog/
|   |   ├── my-first-blog-post.html
|   |   └── my-second-blog-post.html
|   ├── about.html
|   ├── contact.html
|   ├── feed.xml
|   ├── index.html
|   └── sitemap.xml
├── content/
|   └── blog/
|   |   ├── my-first-blog-post.mdx
|   |   └── my-second-blog-post.mdx
|   ├── about.mdx
|   ├── contact.mdx
|   └── index.mdx
└── package.json

Sitemap and RSS feed

The feed.xml and sitemap.xml files are your RSS feed and sitemap. Most websites need these files, so JS.SSG creates them automatically.

Preview your site

You can preview your website before deploying it to a server by running:

jsssg --serve

This will serve your site at http://localhost:8080.

Next steps

Now that you've seen how JS.SSG converts your Markdown into HTML, it's time to customise that HTML using one of JS.SSG's most powerful features: Templates