docs: add profile registration template, site pages, example profile

json-api · ethanresnick · Nov 14, 2018 · Oct 7, 2018 · Oct 20, 2018 · Oct 22, 2018
commit 6f620fa14a78ad2303936db1aee5268568f3aac8
diff --git a/_config.yml b/_config.yml
@@ -13,19 +13,21 @@ whitelist:
   - jekyll-sitemap
   - jekyll-feed
   - jekyll-seo-tag
-  - jekyll-gist
   - jemoji
 incremental: false
 gist:
   noscript: false
+
 # customize github pages
 quiet: false
 markdown: kramdown
 highlighter: rouge
 kramdown:
   input: GFM
   hard_wrap: false
-  auto_ids: false
+  auto_ids: true
+  auto_id_prefix: auto-id-
+  auto_id_stripping: true
   template: '' # cannot customize
   math_engine: mathjax # cannot customize
   syntax_highligher: rouge # cannot customize
@@ -48,6 +50,9 @@ port: 9876
 collections:
   format:
     output: true
+  profiles:
+    output: true
+    permalink: /:collection/:path
 
 defaults:
   - scope:
@@ -57,6 +62,20 @@ defaults:
       layout: page
       show_sidebar: true
       is_spec_page: true
+  - scope:
+      path: ""
+      type: "profiles"
+    values:
+      layout: profile_error
+      is_spec_page: false
+      show_sidebar: false
+  - scope:
+      path: "*/*/*/index.md"
+      type: "profiles"
+    values:
+      layout: profile
+      is_spec_page: false
+      show_sidebar: true
 
 latest_version: 1.0
 excerpt_separator: ""
@@ -84,3 +103,12 @@ quicklinks:
   url: /format/
 - title: Contribute on GitHub
   url: https://github.com/json-api/json-api
+
+profile_categories:
+  - Pagination
+  # these are some other potential categories.
+  # Uncomment them if you're adding a profile in one of these categories.
+  # - Filtering
+  # - Actions/Hypermedia
+  # - Data Modeling
+  # - Deep Querying
diff --git a/_format/1.1/index.md b/_format/1.1/index.md
@@ -2222,6 +2222,11 @@ supported as well.
 3. alter the JSON structure of any concept defined in this specification, 
 including to allow a superset of JSON structures.
 
+
+> If you create your own profile, you are **strongly encouraged to [register](/extensions/#profile-registration) 
+> it** with the JSON API [profile registry](/extensions/), so that others can
+> find and reuse it.
+
 #### <a href="#profiles-updating" id="profiles-updating" class="headerlink"></a> Revising a Profile
 
 Profiles **MAY** be revised over time, e.g., to add new capabilities. However, 

diff --git a/_includes/global_head_assets.html b/_includes/global_head_assets.html
@@ -0,0 +1,32 @@
+<meta charset="utf-8">
+<meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link href="/stylesheets/normalize.css" rel="stylesheet" type="text/css" />
+<link href="/stylesheets/all.css" rel="stylesheet" type="text/css" />
+<link href="/stylesheets/print.css" media="print" rel="stylesheet" type="text/css" />
+<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
+<script src="/javascripts/all.js" type="text/javascript"></script>
+<script src="/javascripts/highlight.pack.js"></script>
+<script>hljs.configure({classPrefix: ''}); hljs.initHighlightingOnLoad();</script>
+
+<link rel="apple-touch-icon" sizes="57x57" href="/alt-favicons/apple-touch-icon-57x57.png">
+<link rel="apple-touch-icon" sizes="60x60" href="/alt-favicons/apple-touch-icon-60x60.png">
+<link rel="apple-touch-icon" sizes="72x72" href="/alt-favicons/apple-touch-icon-72x72.png">
+<link rel="apple-touch-icon" sizes="76x76" href="/alt-favicons/apple-touch-icon-76x76.png">
+<link rel="apple-touch-icon" sizes="114x114" href="/alt-favicons/apple-touch-icon-114x114.png">
+<link rel="apple-touch-icon" sizes="120x120" href="/alt-favicons/apple-touch-icon-120x120.png">
+<link rel="apple-touch-icon" sizes="144x144" href="/alt-favicons/apple-touch-icon-144x144.png">
+<link rel="apple-touch-icon" sizes="152x152" href="/alt-favicons/apple-touch-icon-152x152.png">
+<link rel="apple-touch-icon" sizes="180x180" href="/alt-favicons/apple-touch-icon-180x180.png">
+<link rel="icon" type="image/png" href="/alt-favicons/favicon-32x32.png" sizes="32x32">
+<link rel="icon" type="image/png" href="/alt-favicons/favicon-194x194.png" sizes="194x194">
+<link rel="icon" type="image/png" href="/alt-favicons/favicon-96x96.png" sizes="96x96">
+<link rel="icon" type="image/png" href="/alt-favicons/android-chrome-192x192.png" sizes="192x192">
+<link rel="icon" type="image/png" href="/alt-favicons/favicon-16x16.png" sizes="16x16">
+<link rel="manifest" href="/alt-favicons/manifest.json">
+<link rel="mask-icon" href="/alt-favicons/safari-pinned-tab.svg" color="#0b4e22">
+<link rel="shortcut icon" href="/favicon.ico">
+<meta name="msapplication-TileColor" content="#da532c">
+<meta name="msapplication-TileImage" content="/alt-favicons/mstile-144x144.png">
+<meta name="msapplication-config" content="/alt-favicons/browserconfig.xml">
+<meta name="theme-color" content="#0b4e22">
diff --git a/_includes/global_html_footer.html b/_includes/global_html_footer.html
@@ -0,0 +1,23 @@
+<footer>
+  <div class="site-wrapper">
+    <span>Built with <a href="https://jekyllrb.com/">Jekyll</a> and <a href="http://softwaremaniacs.org/soft/highlight/en/">Highlight.js</a></span>
+    <span class="license">
+      <a rel="license" href="https://creativecommons.org/publicdomain/zero/1.0/"><img src="https://licensebuttons.net/p/zero/1.0/88x31.png" style="border- style: none;" alt="CC0" /></a>
+    </span>
+    <span class="social-links">
+      <a class="twitter" href="https://twitter.com/jsonapi"><i class="icon-twitter"></i><span>Twitter</span></a>
+      <a class="github" href="https://github.com/json-api"><i class="icon-github"></i><span>GitHub</span></a>
+      <a class="forum" href="https://discuss.jsonapi.org"><i class="icon-forum"></i><span>Discussion Forum</span></a>
+    </span>
+  </div>
+</footer>
+<script>
+  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+  ga('create', 'UA-40609539-1', 'jsonapi.org');
+  ga('send', 'pageview');
+
+</script>
diff --git a/_includes/header_offset_2.md b/_includes/header_offset_2.md
@@ -0,0 +1,33 @@
+{% comment %}
+  When we embed the markdown from a user-provided profile specification
+  inside the profile layout, we need to increment each heading level by 2.
+  Kramdown, our markdown parser, provides a `header_offset` option, but
+  Jekyll only allows us to set that globally -- and setting it globally 
+  to two would break our other pages. So, this include lets us take arbitrary
+  HTML (from rendered markdown) and does some liquid string replacements
+  to offset its headings. This is pretty janky (even more so because liquid
+  only allows us to do literal string replacement, not regex replacement),
+  but I think it *should* work robustly, thanks to the fact that angle 
+  brackets (i.e., `<` and `>`) aren't supposed to appear in HTML unencoded,
+  and I imagine Kramdown respects that.
+{% endcomment %}
+{{ include.content
+  | replace: "<h5", "<h6x"
+  | replace: "<h4", "<h6x"
+  | replace: "<h3", "<h5x"
+  | replace: "<h2", "<h4x"
+  | replace: "<h1", "<h3x"
+  | replace: "</h1>", "</h3x>"
+  | replace: "</h2>", "</h4x>"
+  | replace: "</h3>", "</h5x>"
+  | replace: "</h4>", "</h6x>"
+  | replace: "</h5>", "</h6x>"
+  | replace: "<h3x", "<h3"
+  | replace: "<h4x", "<h4"
+  | replace: "<h5x", "<h5"
+  | replace: "<h6x", "<h6"
+  | replace: "</h3x>", "</h3>"
+  | replace: "</h4x>", "</h4>"
+  | replace: "</h5x>", "</h5>"
+  | replace: "</h6x>", "</h6>"
+}}
diff --git a/_includes/profile_url.md b/_includes/profile_url.md
@@ -0,0 +1,5 @@
+{% comment %}
+  Takes the page object for a JSON:API profile spec and returns its url. 
+  This file can't have whitespace outside this comment block or else the 
+  output will be corrupted.
+{% endcomment %}{{ include.page.url | absolute_url | split: "/" | where_exp: "item", "item != 'index'" | join: "/" }}/
diff --git a/_includes/site_navigation.html b/_includes/site_navigation.html
@@ -0,0 +1,13 @@
+<nav class="site-nav">
+  <div class="nav-inner">
+    <ul>
+      {% assign url = page.url|remove:'index.html' %}
+      {% for link in site.navigation %}
+        <li {% if url == link.url or url contains "/profiles/" and link.url contains "/extensions" %}class="active"{% endif %}><a href="{{link.url}}" title="{{link.title}}">{{link.title}}</a></li>
+      {% endfor %}
+      <li class="version">
+        <a href="/format/#status" class="pill">v{{ site.latest_version }} <span class="stable">Stable</span></a>
+      </li>
+    </ul>
+  </div>
+</nav>
diff --git a/_layouts/page.html b/_layouts/page.html
@@ -1,9 +1,7 @@
 <!doctype html>
 <html>
   <head>
-    <meta charset="utf-8">
-    <meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
+    {% include global_head_assets.html %}
 
     {% comment %}
       Below, we're either dealing with a generic page or a page from the
@@ -20,57 +18,15 @@
     {% else %}
       {% assign page_title = page.title %}
     {% endif %}
-    <title>JSON API &mdash; {{page_title|strip }}</title>
-
-    <link href="/stylesheets/normalize.css" rel="stylesheet" type="text/css" />
-    <link href="/stylesheets/all.css" rel="stylesheet" type="text/css" />
-    <link href="/stylesheets/print.css" media="print" rel="stylesheet" type="text/css" />
-    <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
-    <script src="/javascripts/all.js" type="text/javascript"></script>
-    <script src="/javascripts/highlight.pack.js"></script>
-    <script>hljs.configure({classPrefix: ''}); hljs.initHighlightingOnLoad();</script>
-
-    <link rel="apple-touch-icon" sizes="57x57" href="/alt-favicons/apple-touch-icon-57x57.png">
-    <link rel="apple-touch-icon" sizes="60x60" href="/alt-favicons/apple-touch-icon-60x60.png">
-    <link rel="apple-touch-icon" sizes="72x72" href="/alt-favicons/apple-touch-icon-72x72.png">
-    <link rel="apple-touch-icon" sizes="76x76" href="/alt-favicons/apple-touch-icon-76x76.png">
-    <link rel="apple-touch-icon" sizes="114x114" href="/alt-favicons/apple-touch-icon-114x114.png">
-    <link rel="apple-touch-icon" sizes="120x120" href="/alt-favicons/apple-touch-icon-120x120.png">
-    <link rel="apple-touch-icon" sizes="144x144" href="/alt-favicons/apple-touch-icon-144x144.png">
-    <link rel="apple-touch-icon" sizes="152x152" href="/alt-favicons/apple-touch-icon-152x152.png">
-    <link rel="apple-touch-icon" sizes="180x180" href="/alt-favicons/apple-touch-icon-180x180.png">
-    <link rel="icon" type="image/png" href="/alt-favicons/favicon-32x32.png" sizes="32x32">
-    <link rel="icon" type="image/png" href="/alt-favicons/favicon-194x194.png" sizes="194x194">
-    <link rel="icon" type="image/png" href="/alt-favicons/favicon-96x96.png" sizes="96x96">
-    <link rel="icon" type="image/png" href="/alt-favicons/android-chrome-192x192.png" sizes="192x192">
-    <link rel="icon" type="image/png" href="/alt-favicons/favicon-16x16.png" sizes="16x16">
-    <link rel="manifest" href="/alt-favicons/manifest.json">
-    <link rel="mask-icon" href="/alt-favicons/safari-pinned-tab.svg" color="#0b4e22">
-    <link rel="shortcut icon" href="/favicon.ico">
-    <meta name="msapplication-TileColor" content="#da532c">
-    <meta name="msapplication-TileImage" content="/alt-favicons/mstile-144x144.png">
-    <meta name="msapplication-config" content="/alt-favicons/browserconfig.xml">
-    <meta name="theme-color" content="#0b4e22">
+    <title>JSON API &mdash; {{ page_title|strip }}</title>
   </head>
 
   <body>
-     <nav class="site-nav">
-      <div class="nav-inner">
-        <ul>
-          {% assign url = page.url|remove:'index.html' %}
-          {% for link in site.navigation %}
-            <li {% if url == link.url %}class="active"{% endif %}><a href="{{link.url}}" title="{{link.title}}">{{link.title}}</a></li>
-          {% endfor %}
-          <li class="version">
-            <a href="/format/#status" class="pill">v{{ site.latest_version }} <span class="stable">Stable</span></a>
-          </li>
-        </ul>
-      </div>
-    </nav>
+    {% include site_navigation.html %}
     {% if page.show_masthead %}
       <header>
         <div class="content">
-          <h1>JSON API</h1>
+          <h1 id="json-api">JSON API</h1>
           <h2>A specification for building APIs in JSON</h2>
           <div class="quicklinks">
             {% for link in site.quicklinks %}
@@ -103,7 +59,8 @@ <h2>A specification for building APIs in JSON</h2>
                     Upcoming Version (v{{ site.latest_version|plus:0.1 }})
                   </option>
                   <optgroup label="Old Versions/Permalinks">
-                    {% for spec_draft in site.format|sort:'version' %}
+                    {% assign sorted_formats = site.format|sort:'version' %}
+                    {% for spec_draft in sorted_formats %}
                       {% if spec_draft.version and spec_draft.path contains 'index' %}
                         <option value="/format/{{spec_draft.version}}"
                           {% if page.version == spec_draft.version %}selected{% endif%}
@@ -121,7 +78,7 @@ <h1 class="sidebar-top">{{ page_title }}</h1>
           </nav>
         </div>
       {% endif %}
-      <div class="content">
+      <main class="content">
         {% unless page.show_masthead %}
           <h1>
             {{ page_title }}
@@ -136,31 +93,9 @@ <h1>
           {% endif %}
           {{ content }}
         </section>
-      </div>
+      </main>
     </div>
-    <footer>
-      <div class="site-wrapper">
-        <span>Built with <a href="https://jekyllrb.com/">Jekyll</a> and <a href="http://softwaremaniacs.org/soft/highlight/en/">Highlight.js</a></span>
-        <span class="license">
-          <a rel="license" href="https://creativecommons.org/publicdomain/zero/1.0/"><img src="https://licensebuttons.net/p/zero/1.0/88x31.png" style="border- style: none;" alt="CC0" /></a>
-        </span>
-        <span class="social-links">
-          <a class="twitter" href="https://twitter.com/jsonapi"><i class="icon-twitter"></i><span>Twitter</span></a>
-          <a class="github" href="https://github.com/json-api"><i class="icon-github"></i><span>GitHub</span></a>
-          <a class="forum" href="https://discuss.jsonapi.org"><i class="icon-forum"></i><span>Discussion Forum</span></a>
-        </span>
-      </div>
-    </footer>
-    <script>
-      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
-      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
-      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
-      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
-
-      ga('create', 'UA-40609539-1', 'jsonapi.org');
-      ga('send', 'pageview');
-
-    </script>
+    {% include global_html_footer.html %}
   </body>
 
 </html>
diff --git a/_layouts/profile.html b/_layouts/profile.html
@@ -0,0 +1,71 @@
+<!doctype html>
+<html>
+  <head>
+    {% include global_head_assets.html %}
+    {% capture page_title %}&ldquo;{{ page.name | smartify }}&rdquo; Profile{% endcapture %}
+    <title>JSON API &mdash; {{ page_title|strip }}</title>
+  </head>
+
+  <body>
+    {% include site_navigation.html %}
+    <div class="site-wrapper">
+      <div class="sidebar">
+        <nav class="document-outline" id="document-outline">
+          <h1 class="sidebar-top">{{ page.name }}</h1>
+        </nav>
+      </div>
+      <main class="content profile-page">
+        <h1>
+          {{ page_title }}
+        </h1>
+        <section>
+          <h2><a href="#profile-intro" id="profile-intro" class="headerlink"></a>Introduction</h2>
+          <p>This is the specification of <a href="http://jsonapi.org/format/1.1/#profiles">a profile</a> for the JSON:API specification.</p>
+          <p>The url for this profile is <code>{% include profile_url.md page=page %}</code>.</p>
+
+          {% capture extended_description_markdown %}
+            {{ page.extended_description | markdownify }}
+          {% endcapture %}
+          {% include header_offset_2.md content=extended_description_markdown %}
+        </section>
+        {% if page.minimum_jsonapi_version > 1.0 %}
+          <section>
+            <h2>
+              <a href="#profile-jsonapi-req" id="profile-jsonapi-req" class="headerlink"></a>
+              Minimum JSON:API Version
+            </h2>
+
+            <p>This profile requires at least JSON:API version {{ page.minimum_jsonapi_version }}.</p>
+            {% capture minimum_version_markdown %}
+              {{ page.minimum_jsonapi_version_explanation | markdownify }}
+            {% endcapture %}
+            {% include header_offset_2.md content=minimum_version_markdown %}
+          </section>
+        {% endif %}
+        <section id="profile-spec-container">
+          <h2><a href="#profile-spec" id="profile-spec" class="headerlink"></a>Specification</h2>
+          {% include header_offset_2.md content=content %}
+        </section>
+        <section>
+          <h2><a href="#profile-contact" id="profile-contact" class="headerlink"></a>Contact the Author</h2>
+          {% if page.discussion_url %}
+            <p>To discuss or ask questions about this extension, visit
+              <a href="{{ page.discussion_url }}">{{ page.discussion_url }}</a>.</p>
+            <p>You can also contact the author directly:</p>
+          {% endif %}
+          <address>
+            {{ page.author_name }}<br/>
+            <a href="mailto:{{ page.author_email }}">{{ page.author_email }}</a><br/>
+            {% if page.author_website %}
+              <a href="{{ page.author_website }}">{{ page.author_website }}</a><br/>
+            {% endif %}
+            {% if page.author_phone %}
+              <a href="tel:{{ page.author_phone }}">{{ page.author_phone }}</a><br/>
+            {% endif %}
+          </address>
+        </section>
+      </main>
+    </div>
+    {% include global_html_footer.html %}
+  </body>
+</html>