Extension documentation tuning (#898)

 - downgrade scratchblocks until custom block arguments are fixed
 - tune some colors
 - add a proper header
 - fix spacing around horizontal lines
 - migrate away from using .html in docsURI

CONTRIBUTING.md

@@ -43,7 +43,7 @@ To add an extension to the website homepage, modify [`website/index.ejs`](websit
 
 New extensions do not *need* images, but they are highly encouraged. Save the image in the `images` folder with the same folder name and file name (but different file extension) as the extension's source code. For example, if your extension is located in `extensions/TestMuffin/fetch.js`, save the image as `images/TestMuffin/fetch.svg` or `images/TestMuffin/fetch.png`. The homepage generator will detect it automatically. Images are displayed in a 2:1 aspect ratio. SVG (preferred), PNG, or JPG are accepted. PNG or JPG should be 600x300 in resolution. Please add proper attribution to `images/README.md` for *any* resources that were not made by you.
 
-Most extensions shouldn't need external documentation -- it should be obvious what to do just by looking at the blocks. That said, some do need more explanation. Documentation is written in markdown and placed in the `docs` folder with a similar layout to images. For example, documentation for `extensions/TestMuffin/fetch.js` would be saved as `docs/TestMuffin/fetch.md`. Our version of markdown is slightly extended to allow rendering [scratchblocks](https://scratchblocks.github.io/). Just look at the existing documentation for examples. It's not a perfect experience: block colors have to be manually copied, and icons aren't supported, but it's better than what we had before.
+Most extensions shouldn't need external documentation -- it should be obvious what to do just by looking at the blocks. That said, some do need more explanation. Documentation is written in markdown and placed in the `docs` folder with a similar layout to images. For example, documentation for `extensions/TestMuffin/fetch.js` would be saved as `docs/TestMuffin/fetch.md`. Our version of markdown is slightly extended to allow rendering [scratchblocks](https://scratchblocks.github.io/). Just look at the existing documentation for syntax examples. It's not a perfect experience: block colors have to be manually copied, and icons aren't supported, but it's better than what we had before. Once you put your markdown there, you can set a `docsURI` like `https://extensions.turbowarp.org/TestMuffin/fetch`.
 
 Static resources, such as example links, go in the `website` folder. This is where some example assets used by extensions such as fetch are placed.
 

development/builder.js

@@ -145,14 +145,15 @@ IMAGE_FORMATS.set('.jpg', ImageFile);
 IMAGE_FORMATS.set('.svg', SVGFile);
 
 class DocsFile extends DiskFile {
-  constructor (path) {
+  constructor (path, extensionId) {
     super(path);
+    this.extensionId = extensionId;
     this.getDiskPath = null;
   }
 
   read () {
     const markdown = super.read().toString('utf-8');
-    return renderDocs(markdown);
+    return renderDocs(markdown, this.extensionId);
   }
 
   getType () {
@@ -234,10 +235,10 @@ class Builder {
         continue;
       }
       const extensionId = docsFilename.split('.')[0];
-      build.files[`/${extensionId}.html`] = new DocsFile(path);
+      build.files[`/${extensionId}.html`] = new DocsFile(path, extensionId);
     }
 
-    const scratchblocksPath = pathUtil.join(__dirname, '../node_modules/@turbowarp/scratchblocks/build/scratchblocks.min.js');
+    const scratchblocksPath = pathUtil.join(__dirname, '../node_modules/scratchblocks/build/scratchblocks.min.js');
     build.files['/docs-internal/scratchblocks.js'] = new DiskFile(scratchblocksPath);
 
     const extensionFiles = [];

development/docs-template.ejs

@@ -4,6 +4,7 @@
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title><%= headerText %> - TurboWarp Extension Documentation</title>
+    <link rel="canonical" href="https://extensions.turbowarp.org/<%= slug %>">
     <style>
       :root {
         font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
@@ -13,7 +14,7 @@
       @media (prefers-color-scheme: dark) {
         :root {
           color: #eee;
-          background: #111;
+          background: #131313;
         }
       }
 
@@ -32,7 +33,37 @@
       body {
         margin: 0;
         padding: 0;
-        border-top: 4px solid #ff4c4c;
+        line-height: 1.3;
+      }
+
+      nav {
+        background-color: #ff4c4c;
+        color: white;
+        font-weight: bold;
+        font-size: 1.1em;
+      }
+      nav > * {
+        display: flex;
+        align-items: center;
+        max-width: 600px;
+        margin: 0 auto;
+        padding: 0.5rem 0.25rem;
+        gap: 0.5rem;
+        text-decoration: none;
+        color: inherit !important;
+      }
+      nav > *:hover {
+        text-decoration: underline;
+      }
+      nav img {
+        width: 2rem;
+        height: 2rem;
+        flex-shrink: 0;
+      }
+      @media (prefers-color-scheme: dark) {
+        nav {
+          background-color: #333;
+        }
       }
 
       noscript {
@@ -42,13 +73,21 @@
       .container {
         max-width: 600px;
         margin: auto;
+        padding: 0 0.25rem;
+      }
+      h1 {
+        font-size: 2.25rem;
+      }
+      h1, h2, h3, h4, h5, h6 {
+        border-bottom: 1px solid #ccc;
       }
       hr {
         border: none;
         border-top: 1px solid #ccc;
+        margin: 1rem 0;
       }
       @media (prefers-color-scheme: dark) {
-        hr {
+        hr, h1, h2, h3, h4, h5, h6 {
           border-color: #444;
         }
       }
@@ -82,13 +121,20 @@
       }
 
       footer {
-        margin: 16px 0;
+        margin: 1rem 0;
         font-size: small;
       }
     </style>
   </head>
   <body>
-    <div class="container">
+    <nav role="navigation">
+      <a href="/">
+        <img src="/turbowarp.svg" alt="">
+        <span>TurboWarp Extension Gallery</span>
+      </a>
+    </nav>
+
+    <main class="container">
       <h1><%- headerHTML %></h1>
 
       <noscript><p>Enable JavaScript for blocks to render.</p></noscript>
@@ -106,13 +152,15 @@
         </p>
         <p>TurboWarp is not affiliated with Scratch, the Scratch Team, or the Scratch Foundation.</p>
       </footer>
-    </div>
+    </main>
 
-    <script src="/docs-internal/scratchblocks.js"></script>
-    <script>
-      scratchblocks.renderMatching('.render-scratchblocks', {
-        style: 'scratch3'
-      });
-    </script>
+    <% if (usesScratchBlocks) { %>
+      <script src="/docs-internal/scratchblocks.js"></script>
+      <script>
+        scratchblocks.renderMatching('.render-scratchblocks', {
+          style: 'scratch3'
+        });
+      </script>
+    <% } %>
   </body>
 </html>

development/render-docs.js

@@ -23,9 +23,10 @@ md.renderer.rules.fence = function (tokens, idx, options, env, self) {
 
 /**
  * @param {string} markdownSource Markdown code
+ * @param {string} slug Path slug like 'TestMuffin/fetch'
  * @returns {string} HTML source code
  */
-const renderDocs = (markdownSource) => {
+const renderDocs = (markdownSource, slug) => {
   const env = {};
   const tokens = md.parse(markdownSource, env);
 
@@ -50,6 +51,7 @@ const renderDocs = (markdownSource) => {
   const bodyHTML = md.renderer.render(tokens, md.options, env);
 
   return renderTemplate(path.join(__dirname, 'docs-template.ejs'), {
+    slug,
     headerHTML,
     headerText,
     bodyHTML,

docs/CST1229/zip.md

@@ -14,7 +14,7 @@ Most blocks in this extension work with a path format:
  - A `/` at the end denotes a directory, like `folder/`
  - Multiple slashes in a row or trying to go above the root directory will result in an error (usually the block doing nothing or returning the empty value)
 
-## Archive management blocks (link) 
+## Archive management blocks
 
 Blocks for creating and saving the current archive. Only one archive can be open at a time. 
 

extensions/ar.js

@@ -484,7 +484,7 @@
                 color1: "#d10000",
                 color2: "#bd0000",
                 color3: "#af0100",
-                docsURI: "https://extensions.turbowarp.org/ar.html",
+                docsURI: "https://extensions.turbowarp.org/ar",
                 blocks: [
                     {
                         opcode: "enterAR",

extensions/bitwise.js

@@ -30,7 +30,7 @@
 
         color1: '#17cde6',
 
-        docsURI: "https://extensions.turbowarp.org/bitwise.html",
+        docsURI: "https://extensions.turbowarp.org/bitwise",
         menuIconURI: icon,
 
         blocks: [

extensions/box2d.js

@@ -12354,7 +12354,7 @@
           default: "Physics",
           description: "Label for the Griffpatch extension category",
         }),
-        docsURI: "https://extensions.turbowarp.org/box2d.html",
+        docsURI: "https://extensions.turbowarp.org/box2d",
         menuIconURI: menuIconURI,
         blockIconURI: blockIconURI,
         blocks: [

extensions/local-storage.js

@@ -67,7 +67,7 @@
       return {
         id: 'localstorage',
         name: 'Local Storage',
-        docsURI: "https://extensions.turbowarp.org/local-storage.html",
+        docsURI: "https://extensions.turbowarp.org/local-storage",
         blocks: [
           {
             opcode: 'setProjectId',

package.json

@@ -20,13 +20,13 @@
   },
   "homepage": "https://github.com/TurboWarp/extensions#readme",
   "dependencies": {
-    "@turbowarp/scratchblocks": "^3.6.3",
     "@turbowarp/types": "git+https://github.com/TurboWarp/types-tw.git#tw",
     "chokidar": "^3.5.3",
     "ejs": "^3.1.9",
     "express": "^4.18.2",
     "image-size": "^1.0.2",
-    "markdown-it": "^13.0.1"
+    "markdown-it": "^13.0.1",
+    "scratchblocks": "^3.6.2"
   },
   "devDependencies": {
     "eslint": "^8.47.0"