Tagging system - nshebang/nob GitHub Wiki

These are some simple tutorials on how to use Nob's entry tagging system.

What are tags used for?

This is a question you need to answer yourself. If you don't know how enabling the tagging system on your blog would benefit you, you probably don't need it anyway. However, post tagging is usually used for things like classifying posts, adding search scripts, separating posts, SEO stuff and so on.

How can I use tags for my entries?

By default, your entries won't have any tags associated to them, nor will tags be rendered in the HTML static files of your blog. In order to use the tagging system, you need to explicitly add some tags to any of your blog entries and make some changes to your templates so the tag list is rendered by Nob on build time.

[Tutorial 1] How to enable the tagging system

Open your favorite text editor, and edit the metadata of the entry you want to add tags to. Then just add a TAGS field and type any tags you want separated by commas and no new lines whatsoever. For example:

---
TITLE: Entry title
DATE: XX-XX-XXXX
DATE RFC2822: Sun, XX Jan 20XX XX:XX:XX +0000
DRAFT: false
TAGS: cooking, travel, food
---

Adding tags to an entry will enable tags for that specific entry, however, they won't be magically rendered to its HTML page. You need to edit the template page of your blog posts to make Nob render the tags on build time:

<!doctype html>
<html>
<head>
  <meta charset="utf-8"/>
  <title>{{.title}}</title>
</head>
<body>
  <h1>{{.title}}</h1>
  <hr>
  <p>
    <small>{{.date}}</small>
  </p>
  {{.content}}
  <p>
  <!-- The .tags variable is a collection of HTML <span class="nob-tag"> elements that represent your tags -->
  <!-- By default, this variable is not rendered. You need to add it to the HTML code -->
  <small>{{.tags}}</small> 
  </p>
  <hr>
  <small>- <a href="index.html">home</a> -</small>
</body>
</html>

[Tutorial 2] How to implement post categories using the tagging system and javascript

Let's make the tagging system useful. We will implement post categories by classifying posts by their tags. These are our goals:

  1. We should be able to see all the posts that belong to a category by adding a #hash to the URL of our blog index page. For example https://myblog.neocities.org/#cats should only show posts about cats, and https://myblog.neocities.org/ should show all the posts and ignore tags.
  2. We should filter out posts that don't belong to the current #category.
  3. We should be able to see all the posts belonging to a category by clicking the elements.
  4. We should add a "categories menu" to the index page of our blog.

First, let's change our index page template .nob/templates/index.html:

<!doctype html>
<html>
<head>
  <meta charset="utf-8"/>
  <title>Blog</title>
</head>
<body>
  <h1>My blog</h1>
  <hr>
  <!-- We will add the categories menu as a <nav> element -->
  <nav>
  <a href="#">all posts</a>
  <a href="#cats">#cats</a>
  <a href="#cooking">#cooking</a>
  <a href="#anime">#anime</a>
  <hr>
  </nav>

  <!-- We should add the id "entry-list" to the <ul> element containing our entries -->
  <ul id="entry-list">
    {{.entries}}
  </ul>

  <hr>
  <small>- <a href="rss.xml">RSS</a> -</small>

  <!-- This is the script we will use to implement the category system. It should be placed in the root directory of our blog -->
  <script src="categories.js"></script>
</body>
</html>

We should edit .nob/templates/post.html as well:

<!doctype html>
<html>
<head>
  <meta charset="utf-8"/>
  <title>{{.title}}</title>
</head>
<body>
  <h1>{{.title}}</h1>
  <hr>
  <p>
    <small>{{.date}}</small>
  </p>
  {{.content}}

  <!-- Remember to enable tag rendering! -->
  <p>
  <small>{{.tags}}</small>
  </p>

  <hr>
  <small>- <a href="index.html">home</a> -</small>

  <!-- This is the second script we will use -->
  <script src="links.js"></script>
</body>
</html>

Then, we should create the following scripts in the root directory of our blog:

categories.js

window.addEventListener('load', () => {
  const entries = document.querySelectorAll('#entry-list li')
  const hash = window.location.hash.substring(1)

  if (hash.trim() === '' || !entries)
    return

  Array.from(entries).map(li => {
    if (!li.dataset.tags.split(',').includes(hash))
      li.style.display = 'none'
  })
})

window.addEventListener('hashchange', () => location.reload())

links.js

window.addEventListener('load', () => {
  const tags = document.getElementsByClassName('nob-tag')
  Array.from(tags).map(tag => {
    tag.addEventListener('click', () => {
      window.location.href = `index.html${tag.innerText}`
    })
  })
})

After creating these scripts, run nob build to re-build the static HTML files of our blog, then open the index.html and see the magic yourself! Create a few posts with the #cats, #cooking, and #anime tags and you'll notice that they are properly separated by their tags.

[Tutorial 3] Styling the tags

This is probably the easiest thing to do. All tags rendered by nob are <span class="nob-tag"></span> elements. If you want to style them, add something like this to the CSS stylesheet of your blog:

.nob-tag {
  padding: 4px;
  margin: 2px;
  background-color: #000;
  color: #fff;
  font-size: 9pt;
  border-radius: 10px;
}
⚠️ **GitHub.com Fallback** ⚠️