Merge pull request #408 from ipfs/automatic-listing

feat: use frontmatter title and description, automatic lists
ipfs · May 8, 2023 · 7924dd6 · 7924dd6
2 parents 675403b + c6e8718
commit 7924dd6
Show file tree

Hide file tree

Showing 26 changed files with 103 additions and 116 deletions.
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -7,5 +7,6 @@
   "fenced-code-language": false,
   "blanks-around-lists": false,
   "single-trailing-newline": false,
+  "link-fragments": false,
   "line-length": false
 }
diff --git a/Makefile b/Makefile
@@ -1,4 +1,4 @@
-SPEC_GENERATOR_VER=v1.2.0
+SPEC_GENERATOR_VER=v1.3.1
 
 all: website
 

diff --git a/src/_includes/head.html b/src/_includes/head.html
@@ -4,6 +4,7 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width">
   <title>{% if title != 'Home' %}{{ title }} | {% endif %}IPFS Standards</title>
+  {% if description %}<meta name="description" content="{{ description | singleLine }}">{% endif %}
   <link rel="canonical" href="{{ page.url | permalink }}">
   <link rel="stylesheet" href="/css/index.css">
   <link rel="stylesheet" href="/css/ipseity.min.css">

diff --git a/src/_includes/list.html b/src/_includes/list.html
@@ -0,0 +1,7 @@
+<dl>
+  {% assign sortedPosts = posts | sortByOrder %}
+  {%- for post in sortedPosts -%}
+    <dt><a href="{{ post.url }}">{{ post.data.title }}</a></dt>
+    <dd>{{ post.data.description }}</dd>
+  {%- endfor -%}
+</dl>
diff --git a/src/_includes/specs/architecture.html b/src/_includes/specs/architecture.html
diff --git a/src/_includes/specs/http-gateways/http.html b/src/_includes/specs/http-gateways/http.html
diff --git a/src/_includes/specs/http-gateways/web.html b/src/_includes/specs/http-gateways/web.html
diff --git a/src/_includes/specs/ipns.html b/src/_includes/specs/ipns.html
diff --git a/src/_includes/specs/meta.html b/src/_includes/specs/meta.html
diff --git a/src/architecture/index.html b/src/architecture/index.html
@@ -8,7 +8,7 @@
 {% include 'header.html' %}
 
 <main>
-  {% include 'specs/architecture.html' %}
+  {% include 'list.html', posts: collections.architecture %}
 </main>
 
 {% include 'footer.html' %}
diff --git a/src/architecture/principles.md b/src/architecture/principles.md
@@ -1,4 +1,11 @@
 ---
+title: IPFS Principles
+description: >
+  IPFS is a suite of specifications and tools that are defined by two key characteristics: content-addressing and
+  transport-agnosticity. This document provides context and details about these characteristics. In doing so it defines what
+  is or is not an IPFS implementation.
+date: 2023-03-28
+maturity: reliable
 editors:
   - name: Robin Berjon
     email: robin@berjon.com
@@ -9,12 +16,10 @@ editors:
     affiliation:
         name: Protocol Labs
         url: https://protocol.ai/
-maturity: reliable
-date: 2023-03-28
+tags: ['architecture']
+order: 0
 ---
 
-# IPFS Principles
-
 The IPFS stack is a suite of specifications and tools that share two key characteristics:
 
 1. Data is addressed by its contents using an extensible verifiability mechanism, and

diff --git a/src/http-gateways/dnslink-gateway.md b/src/http-gateways/dnslink-gateway.md
@@ -1,15 +1,19 @@
 ---
-maturity: reliable
+title: DNSLink Gateway Specification
+description: >
+  DNSLink Gateways are an extension of Path Gateways that enable hosting a
+  specific content path under a specific DNS name.
 date: 2022-11-09
+maturity: reliable
 editors:
   - name: Marcin Rataj
     github: lidel
   - name: Thibault Meunier
     github: thibmeu
+tags: ['httpGateways', 'webHttpGateways']
+order: 2
 ---
 
-# DNSLink Gateway Specification
-
 DNSLink Gateway is an extension of :cite[path-gateway] that enables hosting a
 specific content path under a specific DNS name.
 

diff --git a/src/http-gateways/index.html b/src/http-gateways/index.html
@@ -12,13 +12,13 @@ <h3>HTTP</h3>
   <p>
     Low-level gateways that expose IPFS resources over HTTP protocol.
   </p>
-  {% include 'specs/http-gateways/http.html' %}
+  {% include 'list.html', posts: collections.lowLevelHttpGateways %}
   <h3>Web</h3>
   <p>
     Designed for website hosting and improved interoperability with web browsers and
     <a href="https://en.wikipedia.org/wiki/Same-origin_policy">origin-based security model</a>.
   </p>
-  {% include 'specs/http-gateways/web.html' %}
+  {% include 'list.html', posts: collections.webHttpGateways %}
 </main>
 
 {% include 'footer.html' %}
diff --git a/src/http-gateways/path-gateway.md b/src/http-gateways/path-gateway.md
@@ -1,6 +1,11 @@
 ---
-maturity: reliable
+title: Path Gateway Specification
+description: >
+  The most versatile form of IPFS Gateway is a Path Gateway. It exposes namespaces, such
+  as /ipfs/ and /ipns/ under an HTTP server root and provides basic primitives for integrating
+  IPFS resources within the existing HTTP stack.
 date: 2023-02-27
+maturity: reliable
 editors:
   - name: Marcin Rataj
     github: lidel
@@ -15,6 +20,8 @@ editors:
     url: https://hacdias.com/
 xref:
   - url
+tags: ['httpGateways', 'lowLevelHttpGateways']
+order: 0
 ---
 
 # Path Gateway Specification

diff --git a/src/http-gateways/subdomain-gateway.md b/src/http-gateways/subdomain-gateway.md
@@ -1,6 +1,11 @@
 ---
-maturity: reliable
+title: Subdomain Gateway Specification
+description: >
+  Subdomain Gateways are an extension of Path Gateways that enable website hosting
+  isolated per CID/name, while remaining compatible with web browsers relative pathing and
+  the security model of the web.
 date: 2023-01-28
+maturity: reliable
 editors:
   - name: Marcin Rataj
     github: lidel
@@ -17,10 +22,10 @@ editors:
 xref:
   - url
   - html
+tags: ['httpGateways', 'webHttpGateways']
+order: 3
 ---
 
-# Subdomain Gateway Specification
-
 Subdomain Gateway is an extension of :cite[path-gateway] that
 enables website hosting isolated per CID/name, while remaining compatible with
 web browsers relative pathing and security model of the web.

diff --git a/src/http-gateways/trustless-gateway.md b/src/http-gateways/trustless-gateway.md
@@ -1,13 +1,18 @@
 ---
-maturity: reliable
+title: Trustless Gateway Specification
+description: >
+  Trustless Gateways are a minimal subset of Path Gateways that allow light IPFS
+  clients to retrieve data behind a CID and verify its integrity without delegating any
+  trust to the gateway itself.
 date: 2022-11-09
+maturity: reliable
 editors:
   - name: Marcin Rataj
     github: lidel
+tags: ['httpGateways', 'lowLevelHttpGateways']
+order: 1
 ---
 
-# Trustless Gateway Specification
-
 Trustless Gateway is a minimal _subset_ of :cite[path-gateway]
 that allows light IPFS clients to retrieve data behind a CID and verify its
 integrity without delegating any trust to the gateway itself.

diff --git a/src/http-gateways/web-redirects-file.md b/src/http-gateways/web-redirects-file.md
@@ -1,15 +1,20 @@
 ---
-maturity: reliable
+title: Web _redirects File Specification
+description: >
+  The Redirects File specification is an extension of the Subdomain Gateway and DNSLink Gateway specifications that
+  enables URL redirects or rewrites by adding redirect rules to a0 file stored underneath the root CID of a web
+  site.
 date: 2023-01-28
+maturity: reliable
 editors:
   - name: Justin Johnson
     github: justincjohnson
   - name: Marcin Rataj
     github: lidel
+tags: ['httpGateways', 'webHttpGateways']
+order: 4
 ---
 
-# Web _redirects File Specification
-
 The Web Redirects File specification is an extension of the Subdomain Gateway and DNSLink Gateway specifications.
 
 Developers can enable URL redirects or rewrites by adding redirect rules to a file named `_redirects` stored underneath the root CID of their web site.

diff --git a/src/index.html b/src/index.html
@@ -68,7 +68,7 @@ <h3><a href="/architecture/">Architecture</a></h3>
           These documents define the architectural principles that IPFS is built upon, and can be used as tools to evaluate
           implementations and applications of IPFS.
         </p>
-        {% include 'specs/architecture.html' %}
+        {% include 'list.html', posts: collections.architecture %}
       </section>
       <section>
         <h3><a href="/meta/">Meta</a></h3>
@@ -77,23 +77,22 @@ <h3><a href="/meta/">Meta</a></h3>
           project work: what the core values are, what the governance model is, how to produce documents,
           etc.
         </p>
-        {% include 'specs/meta.html' %}
+        {% include 'list.html', posts: collections.meta %}
       </section>
       <section>
         <h3><a href="/http-gateways/">HTTP Gateways</a></h3>
         <p>
           IPFS Gateway acts as a bridge between traditional HTTP clients and IPFS. Through the gateway, users can download files,
           directories and other IPLD data stored in IPFS as if they were stored in a traditional web server.
         </p>
-        {% include 'specs/http-gateways/http.html' %}
-        {% include 'specs/http-gateways/web.html' %}
+        {% include 'list.html', posts: collections.httpGateways %}
       </section>
       <section>
         <h3><a href="/ipns/">InterPlanetary Naming System</a></h3>
         <p>
           The InterPlanetary Naming System (IPNS) is a naming system responsible for creating, reading and updating mutable pointers to data.
         </p>
-        {% include 'specs/ipns.html' %}
+        {% include 'list.html', posts: collections.ipns %}
       </section>
     </div>
   </section>

diff --git a/src/ipns/index.html b/src/ipns/index.html
@@ -7,7 +7,7 @@
 {% include 'header.html' %}
 
 <main>
-  {% include 'specs/ipns.html' %}
+  {% include 'list.html', posts: collections.ipns %}
 </main>
 
 {% include 'footer.html' %}
diff --git a/src/ipns/ipns-pubsub-router.md b/src/ipns/ipns-pubsub-router.md
@@ -1,17 +1,19 @@
 ---
-maturity: reliable
+title: IPNS PubSub Router
+description: Specifies how to publish and retrieve IPNS records using libp2p PubSub router.
 date: 2022-11-09
+maturity: reliable
 editors:
   - name: Adin Schmahmann
     github: aschmahmann
   - name: Marcin Rataj
     github: lidel
 xref:
   - ipns-record
+tags: ['ipns']
+order: 1
 ---
 
-# IPNS PubSub Router
-
 :ref[InterPlanetary Naming System (IPNS)]  is a naming system responsible for the creating, reading and updating of mutable pointers to data.
 IPNS consists of a public/private asymmetric cryptographic key pair, a record type and a protocol.
 Part of the protocol involves a routing layer that is used for the distribution and discovery of new or updated IPNS records.

diff --git a/src/ipns/ipns-record.md b/src/ipns/ipns-record.md
@@ -1,6 +1,10 @@
 ---
-maturity: reliable
+title: IPNS Record and Protocol
+description: >
+  Specifies the IPNS protocol in a language-agnostic manner, allowing everyone to
+  create a compatible IPNS Record Publisher or Resolver.
 date: 2023-02-13
+maturity: reliable
 editors:
   - name: Vasco Santos
     github: vasco-santos
@@ -12,11 +16,11 @@ editors:
     github: hacdias
     url: https://hacdias.com/
   - name: Gus Eggert
-    github: guseggert 
+    github: guseggert
+tags: ['ipns']
+order: 0
 ---
 
-# IPNS Record and Protocol
-
 The InterPlanetary File System (IPFS) is powered by content-addressed data, which by nature is immutable: changing an object would change its hash, and consequently its address, making it a different object altogether. However, there are several use cases where we benefit from having mutable data. This is where the InterPlanetary Naming System (IPNS) gets into the equation. IPNS records provide cryptographically verifiable, mutable pointers to objects.
 
 ## Introduction

diff --git a/src/meta/code-of-conduct.md b/src/meta/code-of-conduct.md
@@ -1,5 +1,8 @@
 ---
+title: Code of Conduct
+description: The code of conduct that all community participants are held to.
 date: 2015-03-19
+maturity: stable
 editors:
     - name: Juan Benet
       github: jbenet
@@ -15,10 +18,10 @@ editors:
       github: hsanjuan
     - name: Jim Garrison
       github: garrison
+tags: ['meta']
+order: 0
 ---
 
-# IPFS Community Code of Conduct
-
 We believe that our mission is best served in an environment that is friendly, safe, and accepting, and free from
 intimidation or harassment. Towards this end, certain behaviors and practices will not be tolerated.
 

diff --git a/src/meta/index.html b/src/meta/index.html
@@ -9,7 +9,7 @@
 {% include 'header.html' %}
 
 <main>
-  {% include 'specs/meta.html' %}
+  {% include 'list.html', posts: collections.meta %}
 </main>
 
 {% include 'footer.html' %}