Basics
The fundamentals of Surfgreen.
At a very high level, a Surfgreen site is made of two kinds of files: pages, and blocks. Each plays a certain role, and they work together to build your site.
Of course, websites also include lots of other files, like CSS, JavaScript, and media assets like images. We'll put those aside for a second, and just focus on how Surfgreen presents the primary content of a URL to a visitor.
Pages
A page contains the main content of a single page on your site — in other words, a single URL that a visitor would open in their web browser.
Every page has two parts to it: frontmatter, which defines the page title, and any other metadata [^metadata] you'd like to include; and content, which is the actual content of the page. Content is made of Markdown [^markdown] and HTML, and ends in a .md extension.
[^metadata]: Per Wikipedia, metadata "is 'data that provides information about other data', but not the content of the data."
As an example, consider a website about somebody's personal musical instrument collection. If you have a page about, say, an electric guitar, the site content might include some body text about and images of the guitar, while the metadata might include the page title, and perhaps specify a category called "guitars". You might even have additional metadata specific to your needs, specifying the instrument brand as "Fender", and the instrument color as "candy apple red".
[^markdown]: A lightweight plain text format that automatically converts into HTML. If you're not familiar with Markdown, you can read about the syntax on the Markdown project website.
A simple page might look like this:
title: My First Page
category: samples
~~~
This is the page content.
In this example, the frontmatter includes title and category metadata fields; the page content comes after the ~~~ marker.
Only the title is required. You can include any other fields you'd like and use them throughout your site.
You can also include HTML in page content:
title: My First Page
category: samples
~~~
<div id="intro">
This is the page content.
</div>
Blocks
A block is a snippet of HTML that helps form a full page on your site. If you've used site builders before, it's kind of like a template.
Blocks can include anything that would be valid in a full HTML page: HTML markup, as you'd expect, as well as inline CSS and JavaScript. There's also some syntax that Surfgreen uses for special functionality, which we'll get to in a bit.
Every Surfgreen site automatically includes three blocks: the header block, body block, and footer block. Within each of those, you can create and insert any additional blocks you want.
At build time, Surfgreen takes the header, body, and footer blocks, parses the page content and any included blocks, and spits out a full HTML page, which can be presented to your site's visitors.
Blocks are created as HTML files, with a .html extension.
For example, your header.html block might be:
<!DOCTYPE html>
<html lang="en">
<head>
<title>My Site – {{title}}</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
body.html:
<div class="container">
{{content}}
</div>
And footer.html:
</body>
</html>
(How do those {{curly braces}} work? We'll come back to them.)
Site organization
Everything in your site, including pages and blocks, lives in your site folder. Within the site folder are a number of items, but the one we'll focus on is contents. That's where you actually design and build your site.
Your blocks go in contents/blocks; your pages can be anywhere else in contents.
When Surfgreen builds your site, it maps your pages to how you've organized them in contents. You can also nest pages, and Surfgreen will detect them.
So, if you have a page at:
contents/about.md
It will appear on your site at:
(yourSiteUrl)/about.html
Surfgreen also supports URLs without HTML extensions by storing pages in subfolders — then naming the page index or by its subfolder. So, if you have a page at:
contents/about/about.md
or:
contents/about/index.md
It will appear at your site at:
example.com/about/
Your home page can be called home.md or index.md, and should be located directly in contents.
Within your site, there's also a build folder; this is where Surfgreen eventually outputs your final site, and we'll explore that in the last chapter.
Those are the basics of how Surfgreen works. Now, let's look at how to actually assemble pages using Surfgreen's syntax.