Getting Started

Hello! I'm really glad you're interested in creating a new website with Clear Label.

Before we begin

You should have some familiarity with what a URL is and some basic HTML. You should also understand the Liquid templating language. You don't need to be an expert in any of this by any means to follow this guide, but we'll be building on all of these concepts.

If any of these seems wrong or is just too hard to follow, and/or you have additional questions that aren't covered by this guide or other help documents on this website, please don't hesitate to email me and ask questions. Thanks!

Structure

Get ready for a lot of proper nouns: A Clear Label Site is made up of Pages. One Page will create one or more Renders, which are the actual HTML files that users will see in their browsers.

You can create structured content by defining Types. One piece of content made with a Type is known generically as a Record, but is usually called by the name of its Type. For example, if you create a Type called "Articles," the Records of that Type become Articles.

You can create Templates to reuse bits of HTML across many Pages. Finally, there are Assets, which are images or any other files that are served by your Site but aren't otherwise editable.

Creating a Site

After logging in to the Clear Label Editor, click "New Site." Enter a Title and a Slug. Title can be anything you like; Slug has to be lowercase and can only consist of letters, numbers, and hyphens. If you entered first-site here, your site would be visible at first-site.clearlabel.net. Note that these slugs must unique across all of Clear Label, so certain slugs might not be available if someone else has already used them.

Creating a Page

Let's create a homepage! From the main menu of your Site in the Clear Label Editor, navigate to "Pages" and then click "New Page."

Give your new Page a name, like "Home." This is just for you to be able to recognize this page in the Editor later; it won't be shown to your visitors. Then set a URL—this is where visitors will go to see this page. Let's just use / for now, so this page is the first thing people see.

Enter some HTML in the Content field. Maybe something like this:

<h1>Hello world! This is my website!</h1>

Now save, go back to the main menu for your site, and click "View Site." There's your homepage!

If you View Source, you'll see that the HTML that's been rendered is exactly what you typed in the Page editor. If you'd like, you can add more detail to this page, including <head> and <body> tags, CSS, and so on.

Adding a Type

Writing HTML is fine, but it's not great for complicated or repetitive information content. That's what Types are for!

Let's set up a way to manage Articles on our site. Go back to the menu in the Editor, then navigate to Types and click "New Type."

For Name, let's use articles. Note that it's plural and lowercase. Type names are used in our code, so they must consist only of letters, numbers, and underscores, and two Types on the same Site cannot have the same name.

For Label and Singular Label, we'll enter "Articles" and "Article," respectively. These are used in the Editor to help you understand what kind of thing you're editing. In this case, it's an Article!

A Description is optional. It shows up in the Editor and can be useful on a team to help describe what a given Type is for. Let's say that Articles are self-explanatory and skip it for now.

Now it's time to add a few Fields to our Type. You can think of this like designing a form that you'll use later when you're creating Records of this Type. Similar to the Type itself, each Field has a human-friendly Label and a machine-friendly Name. They also have a type, which tells Clear Label what kind of information this is. It might be a short bit of text like a Title, or a long bit of text with formatting, or a date, or a color, or a link to another Record! I welcome you to explore how different types behave and what options they offer you. For now, let's just create these Fields:

  1. Label: "Title;" name: "title;" type: "Text"
  2. Label: "Body;" name: "body;" type: "Multi-line Text"
  3. Label: "Published;" name: "published;" type: "Date/Time"
  4. Label: "Slug;" name: "slug;" type: "Slug"

Save your new Type and go back to the Menu. You'll see a new Menu item called "Articles." This represents the collection of Records for the Type you just made. Neat!

Creating Records

From the menu, click "Articles," then "New Article." You'll see a form with some fields that should look familiar—they're based on the Fields you entered for your Article Type! If you were to go back to that Type and add more Fields, they'd show up on this form too.

Fill these fields in save. Do it a couple times to create a few Articles. Have fun making up some fake content, or maybe you'll feel inspired to write some really heartfelt blog posts. It's up to you!

Displaying Records

Now we have some Articles, but they're not visible on our website. Let's fix that.

Go back to the Menu, then to Pages, and open our Home page. At the bottom of the Page's content, add this block of code:

<ul>
  {% for article in collections.articles %}
    <li>
      <a href="/{{ article.slug }}">
        {{ article.title }}
      </a>
    </li>
  {% endfor %}
</ul>

Save, and go look at your site. You should see a list of all your Articles! We added some code here in a language called Liquid. We'll be using Liquid a lot on Clear Label, so I recommend reading the docs to get familiar with the tags and filters available to you.

You might notice that even though we have links for all of our articles, they don't lead to real pages yet. Let's fix that.

Rendering Pages with Records

You can create many unique Pages in Clear Label to add pages to your website, but a lot of pages on a website will often have something in common. A great example of this is for the pages that present our Articles—each Article has unique content, but we'll always want to show their Title, Body, and a Published date in a consistent fashion. In Clear Label vocabulary, the general rules for displaying this content is a Page, and all the different versions of that Page that we publish for our content are called Renders.

Let's create a new Page and call it "Article Permalink." We'll make all the URLs for our article permalink pages equivalent to their slugs; my Article with a slug of "my-coolest-article-yet" should be readable at my-cool-site.clearlabel.net/my-coolest-article-yet.

The URL for this Page could be literally typed out as /my-coolest-article-yet, and that would work just fine…for this one Article. But we're not making a permalink page for one Article; we're making a permalink page for every Article. The way to tell Clear Label that this Page should create multiple Renders with different URLs is to add comma-separated terms to your Page's URL.

The URL for this page could instead by literally typed out as /my-coolest-article-yet,another-day. Now we'd get two Renders of this Page at two different URLs: /my-coolest-article-yet and /another-day. But then every time we wrote a new Article, we'd need to copy its slug into this URL.

Instead, we can use Liquid in the URL field! Try this:

/:slug,{{ collections.articles | map: "slug" | join: "," }}

This is the same thing as before, but instead of manually typing all of our Article's slug, we're generating a long string them with code. Clear Label will now use this code to create a new Render of this Page for every Article. Wow!

You'll notice that we added another term before the others: :slug. If the first term in a comma-separated list of URL terms starts with a colon, it won't create a Render, but it will expose that term as a variable in your Content.

In the Content of our Page, try entering this:

{% assign article = collection.articles | find: "slug", params.slug %}
<h1>{{ article.title }}</h1>
<p><i>Published {{ article.published }}</i></p>
{{ article.body | markdownify }}

What happened here? Let's review:

  1. We created a new variable with Liquid called article by finding one Record in our articles collection whose slug Field matches the slug param in our URL (which we named with that special :slug term).
  2. We printed content to the page using our variable, as before.
  3. We used a special markdownify filter to translate our Contenet field from Markdown to HTML. You don't need to do this—you could type out HTML in your Article Records and print it directly, or set the Content Field's type to "Blocks" to use a rich text editor when you're writing your Articles. But if you want to use Markdown, that's the way to do it.

Save your Page and go back to your site. Those links on your home page should now link to your articles! Wow!

Reusing HTML with Templates

By now you've tried almost every feature of Clear Label and you're ready to start defining, creating, and publishing content of all types. One last thing you might find handy is the ability to create Templates. These are reusable bits of HTML and Liquid that you can include on any Page, or even in other Templates, using the render tag. You can share a common HTML layout across all your Pages, or define a site header that is copied across multiple other templates, or…whatever you want.

A Template also offers you the option to define custom Blocks for use on any Field that is set to the "Blocks" type. These Fields are generally used for rich text, but any Templates you register as Blocks can be inserted among your rich text and rendered with whatever data you like. Block Fields work just like Type Fields.

What's next?

If you're just browsing and don't have access to Clear Label yet, I hope this has excited you. If you want to give it a try and start making websites with Clear Label, please email me and I'll let you in!