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.
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:
- Content (a website without content is nothing)
- Templates (a way to choose how to display you content)
- 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 (
.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.
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](https://www.google.com) 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?
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.
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
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
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:
This will serve your site at http://localhost:8080.
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