[Feature request] Tag (keywords) support

[noraj]

Adding tags (keywords) in frontmatter (meta-data) will generate a page referencing all pages containing this page.

Example:

In frontmatter you add (in YAML for example):

---
tags:
    - dev
    - python
---

So it will create an endpoint http://example.org/tags/dev and http://example.org/tags/python referencing, respectively, all pages containing the dev tag and the python tag.

Then on the page of the documentation where there is such a tags frontmatter, the page will contain some tag link #dev and #python respectively referencing the previously mentioned endpoints.

Example on my blog using Hexo:

Why

Imagine I want to build a hacking documentation with a tree like that (for, let's say, my OSCP exam preparation):

- Admin # Machines from the Admin network, containing a write-up for each machine
  - Machine 1 # tags: [eop,windows]
  - Machine 2 # tags: [network,linux]
  - ...
- Cheat sheets # for various topics
  - Elevation of Privilege # tags: [eop]
  - Metasploit # tags: [exploit]
  - MS SQL Server # tags: [mssql,windows]
  - Network # tags: [network]
  - PWK/OSCP Specific
  - Pivoting # tags: [pivoting,network]
  - ...
- Connectivity
  - Machines
  - PWK Lab
  - Remote desktop
  - ssh-hostkey # tags: [ssh]
- Dev # Machines from the Dev network, containing a write-up for each machine
  - Machine 1
  - Machine 2
  - ...
- Exam
  - Exam specific
  - ...
- IT # Machines from the IT network, containing a write-up for each machine
  - Machine 1
  - Machine 2
  - ...
- Public # Machines from the Public network, containing a write-up for each machine
  - Machine 1
  - Machine 2
  - ...
- Tools
  - Nmap # tags: [network,scanner]
  - John the ripper # tags: [cracking,password,hash]
  - gcc # tags: [compilation,exploit]
  - dnsrecon # tags: [osint,dns]
  - dnsenum # tags: [osint,dns]
  - cmsmap # tags: [cms,web]
  - ncat # tags: [backdoor,network,scanner]
  - recon-ng tags: [osint]
  - snmpwalk # tags: [snmp,network]
  - snmpbrute # tags: [snmp,network]
  - onesixtyone # tags: [snmp,network]
  - ...

So I want to be able to search for a keyword (tag) like snmp and see all machines write-up where I attacked snmp, all cheat sheets explaining snmp stuff, all tools I can use to exploit snmp, etc.

Without tag support this is impossible.

One could say: "But there is already the search feature parsing the content of pages" yeah but this is automatic and introduce a lot of false positive (content containing a keywork but not really about it) and false negative (content not containing the keywork but actually talking about it) when the tag feature will be manual so there will be only exact matches.

I could also provide argumentation Why this shouldn't be theme dependent or plugin based. Some big companies like Docker, Joomla, or the Mozilla foundation are using documentation with tags.

[noraj]

There are keywords in page configuration (https://hyperbook.openpatch.org/configuration/page) but they are used only for SEO, they could be re-used for that purpose displayed on each page and generating a tag index.

[mikebarkmin]

This sounds like a great feature and your explanation on how it should work is very reasonable. I will try to work on an implementation starting next week. 👍

Currently we have terms, which will show in the glossary (https://hyperbook.openpatch.org/elements/glossary). I will try to think about what both will differentiate or if I could combine them.

[mikebarkmin]

I think the glossary feature does cover this use-case. Here are the steps to reproduce the docker documentation.

a-page.md

# A Page

🏷: :t[standards], :t[compliance], :t[security]

Then you have to create three pages in the glossary folder:

glossary/standards.md

# Standards

A brief description.

glossary/compliance.md

# Compliance

Another brief description.

glossary/security.md

# Security

All about security.

At the end of each glossary page, all referenced sites will be displayed.

[noraj]

I have a few remarks:

• I can't make this example work or this one. Even when I copy paste the default hyperbook.md glossary to hyperbook2.md and change the frontmatter to name: Hyperbook2 I get a 404 on http://localhost:3000/glossary/hyperbook2. (I was using the CLI getting started install). Update:I needed to remove vdirectory.book.json and vdirectory.glossary.json to make it work so those files are recreated because even killing and re-lauching npx hyperbook dev doesn't work.
• Having to create a glossary page manually for each tag is annoying. At least, there should be an anonymous glossary feature so that a default empty glossary page exist when a tag is clicked.
• It's also annoying to have to use a tag helper :t[hyperbook2] in the content instead of a node in the frontmatter. One doesn't necessary want to display it in the content, also it doesn't make tags re-usable for other features or plugins. It also prevent from making a theme where the tags are automatically displayed on a specific place.

It looks like the actual implementation of glossary is a glossary and does not really answer the tag need.