Content Templating Tutorial
Goal
In this lesson we will create a reusable layout template using the ht-content attribute, and then create our first web page using HyperTemplates.
What is content templating?
Why do we make websites? For the same reason we visit them: it's all about the content! 👀
The primary function of any good document or website layout template is to create space for the content. For example, this web page was created from a template that has a header and footer full of links and other information to help you navigate around this website, but its primary purpose is to hold the content you are currently reading.
Content templating in HyperTemplates is really easy. Let's see how it works in these first few exercises.
Exercises
- EXERCISE 1: Create a layout
- Write layouts in pure-HTML.
HyperTemplates layouts are HTML files. Let's create a directory for our layout files, and add our first layout.
1mkdir layouts/ 2touch layouts/default.htmlNow lets add a basic layout to
layouts/default.html.layouts/default.html 1<html lang='en-US'> 2 <head> 3 <meta charset='utf-8'> 4 <title>Learn HyperTemplates</title> 5 </head> 6 <body> 7 <main> 8 <article> 9 <h2>Hello, world</h2> 10 <p> 11 This is an <a href='https://developer.mozilla.org/en-US/docs/Web/HTML'>HTML</a> layout! 12 </p> 13 </article> 14 </main> 15 </body> 16</html>This layout is a simple HTML document with a header and a paragraph. Let's view this document in our browser:
1open layouts/default.htmlThe problem with this layout is that we can't reuse it without modifying the HTML. This is where templating comes in. Let's move on to step 2 to convert this layout into a reusable template.
- EXERCISE 2: Create a layout template
- Make a layout reusable using template attributes.
Let's modify our layout so we can easily create new pages using this layout as a temlpate.
layouts/default.html 1<html lang='en-US'> 2 <head> 3 <meta charset='utf-8'> 4 <title>Learn HyperTemplates</title> 5 </head> 6 <body> 7 <main> 8 <article ht-content='markdown:content'> 9 <h2>Hello, world</h2> 10 <p> 11 This is an <a href='https://developer.mozilla.org/en-US/docs/Web/HTML'>HTML</a> layout! 12 </p> 13 </article> 14 </main> 15 </body> 16</html>This layout templates the
<article>element using theht-contentattribute.The
markdown:prefix in ourht-contentattribute tells HyperTemplates to format thecontentas Markdown.Now let's move on to step 3 to create a new page using this layout as a template.
- EXERCISE 3: Create a page
- Write content using Markdown.
HyperTemplates content comes from data files. Each content data file represents a page. The most common format for data files is called Markdown. Let's create a directory for our content data files, and add our first page.
1mkdir content/ 2touch content/index.mdAdd some content to
content/index.md.content/index.md 1## Hello, world 2 3This is my first HyperTemplates page!The body of a markdown document (
index.md) is accessible to HyperTemplates as the template datacontentproperty – the same property our layout will use to populate our template.OK, let's render our first page using HyperTemplates.
1hyperctl render --data content/index.md --layout layouts/default.html > index.htmlThis command created a file called
index.html. We can open this file in a text editor to see what it looks like, or we can view it in a browser!1open index.htmlDid you notice? The contents of our layout template
<article>element were replaced with the content in ourcontent/index.mdfile. 💥 - EXERCISE 4: Template the page title
- Let's modify our layout template so we can update the page title.
First, let's modify
<title>element of our layout template.layouts/default.html 1<html lang='en-US'> 2 <head> 3 <meta charset='utf-8'> 4 <title ht-content='title'>Learn HyperTemplates</title> 5 </head> 6 <body> 7 <main> 8 <article ht-content='markdown:content'> 9 <h2>Hello, world</h2> 10 <p> 11 This is an <a href='https://developer.mozilla.org/en-US/docs/Web/HTML'>HTML</a> layout! 12 </p> 13 </article> 14 </main> 15 </body> 16</html>Now let's update our page data file with a title property.
content/index.md 1--- 2title: "Learn HyperTemplates: Lesson 1" 3--- 4 5## Hello, world 6 7This is my first [HyperTemplates](https://hypertemplates.net) page!HyperTemplates supports Markdown frontmatter – a block of metadata properties at the front of the markdown document. Markdown frontmatter blocks always begin and end with a line containing three hyphens (
---). The contents of the frontmatter block are formatted with YAML, which means we can all all sorts of information to our page data files. In this case we only need to add a title, which we've done by adding atitle:key, with the value of"Learn HyperTemplates: Lesson 1".Did you notice? We made an extra change to line 7 of our
content/index.mdfile. This is how you create a link using Markdown. This step isn't required to complete the tutorial, but we wanted to include this example in case you were wondering how to replicate the link inlayouts/default.html's example paragraph using Markdown. ✨OK, let's re-render our page and see what happens.
1hyperctl render --data content/index.md --layout layouts/default.html > index.htmlIf you still have
index.htmlopen in your browser you can refresh the page, otherwise open it again:1open index.htmlTo view a website or page title in a browser, hover over the browser tab, or use "view source" to inspect the rendered HTML. Otherwise, just open index.html in your text editor.
Discussion
In this lesson, we've just scratched the surface of what HyperTemplates can do.
We created a simple HTML layout and turned it into a reusable template with the ht-content attribute.
We also created our first web page using HyperTemplates!
The first of many!
Core Concepts
Learn more about the concepts in this lesson:
Do you have any questions and/or feedback about ht-content or this "Learn HyperTemplates" tutorial?
Join the @hypertexting.community and visit the "Getting Started" category. 💬
When you're ready, let's go ahead and move on to lesson 2. 👉