Implement default layouts and fix bugs

bcomnes · Sep 15, 2021 · 0536cd0 · 0536cd0
1 parent 156bc33
commit 0536cd0
Show file tree

Hide file tree

Showing 48 changed files with 424 additions and 18 deletions.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -8,18 +8,18 @@ on:
         required: true
 
 env:
-  node_version: 14
+  node_version: 16
 
 jobs:
   version_and_release:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2.3.4
+    - uses: actions/checkout@v2
       with:
         # fetch full history so things like auto-changelog work properly
         fetch-depth: 0
     - name: Use Node.js ${{ env.node_version }}
-      uses: actions/setup-node@v2.2.0
+      uses: actions/setup-node@v2
       with:
         node-version: ${{ env.node_version }}
         # setting a registry enables the NODE_AUTH_TOKEN env variable where we can set an npm token.  REQUIRED

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -9,12 +9,12 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        node: [14]
+        node: [16]
 
     steps:
-    - uses: actions/checkout@v2.3.4
+    - uses: actions/checkout@v2
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v2.2.0
+      uses: actions/setup-node@v2
       with:
         node-version: ${{ matrix.node-version }}
     - run: npm i

diff --git a/.gitignore b/.gitignore
@@ -2,3 +2,4 @@ node_modules
 sandbox.js
 .nyc_output
 package-lock.json
+public
diff --git a/README.md b/README.md
@@ -276,6 +276,9 @@ If you end up trying it out, please open any issues or ideas that you have, and
 - [x] Static asset copying.
 - [x] CLI build command
 - [x] CLI watch command
+- [ ] Multiple layout files
+- [ ] More page sourced variables
+- [ ] Git sourced variables (first touched, last update, git shas, github urls etc).
 - [ ] More robust error handling
 - [ ] More efficient watch rebuilding
 - [ ] Pluggable page types
@@ -290,3 +293,5 @@ If you end up trying it out, please open any issues or ideas that you have, and
 ## License
 
 MIT
+
+[uhtml]: https://github.com/WebReflection/uhtml
diff --git a/examples/basic/package.json b/examples/basic/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "basic",
+  "version": "0.0.0",
+  "description": "",
+  "type": "module",
+  "scripts": {
+    "build": "siteup"
+  },
+  "keywords": [],
+  "author": "Bret Comnes <bcomnes@gmail.com> (https://bret.io/)",
+  "license": "MIT",
+  "devDependencies": {
+    "@siteup/cli": "../../."
+  },
+  "dependencies": {
+    "uhtml-isomorphic": "^1.0.1",
+    "mine.css": "^4.6.1"
+  }
+}
diff --git a/examples/basic/src/README.md b/examples/basic/src/README.md
@@ -0,0 +1,16 @@
+---
+md-files: support yaml frontmatter!
+---
+# Minimal siteup example
+
+This example demonstrates a example of a minimal website, no customization.
+
+It's just a `src` folder with a few markdown files that link to each other. Markdown files can link directly to their markdown counterparts so navigation works inside GitHub's built in markdown source navigator.
+
+- [loose-file.md](./loose-file.md)
+- [nested-md](./md-page/README.md)
+- [sub-page](./md-page/sub-page/README.md)
+
+Also notice how the title of this document set the `title` variable for the page, and renders in the title `<head>` properly.
+Page builders can implement variable extraction based on assumptions like this for a given document type.
+More automatic variable extraction is planned, like `git` metadata (first commit date, last commit date that touched the file. etc).
diff --git a/examples/basic/src/client.js b/examples/basic/src/client.js
@@ -0,0 +1,6 @@
+console.log('This client bundle only loads in the root page.')
+
+// Each page folder can have a client.js file in it.
+// The client.js file is treated as an entry point script for just the
+// page it is associated with, but all dependencies are de-duped via
+// esbuild.
diff --git a/examples/basic/src/conflict-page/README.md b/examples/basic/src/conflict-page/README.md
@@ -0,0 +1,5 @@
+# Conflict README
+
+This is a conflicting README file.
+
+Pages with conflicts don't get built, but any valid static assets or sub-pages do, though your build will exit with an error, which should block production.
diff --git a/examples/basic/src/conflict-page/page.html b/examples/basic/src/conflict-page/page.html
@@ -0,0 +1,3 @@
+<div>
+  A conflicting html page.
+</div>
diff --git a/test-project/src/conflict-page/page.js → examples/basic/src/conflict-page/page.js b/test-project/src/conflict-page/page.js → examples/basic/src/conflict-page/page.js
diff --git a/examples/basic/src/global.client.js b/examples/basic/src/global.client.js
@@ -0,0 +1,4 @@
+console.log('The global client is loaded on every page.')
+
+// Try to keep this file as small as possible.
+// Use if for things like global theme switchers or analytics scripts
diff --git a/examples/basic/src/global.css b/examples/basic/src/global.css
@@ -0,0 +1,9 @@
+@import 'mine.css';
+@import 'mine.css/dist/layout.css';
+
+/* The global.css in the root directory of the site is loaded on every page. */
+
+/* You can import styles out of node_modules by referencing their bare-name */
+/* You can import styles from a relative path as well, though usually that is
+only used in page scpped style.css files */
+/* See https://github.com/postcss/postcss-import for details */
diff --git a/examples/basic/src/global.vars.js b/examples/basic/src/global.vars.js
@@ -0,0 +1,10 @@
+// The global.vars.js file should export default either an object, function that
+// returns an object or an async function that returns an object.
+//
+// These variables are available to every page, and have the lowest precedence.
+
+export default async function () {
+  return {
+    siteName: 'siteup basic'
+  }
+}
diff --git a/examples/basic/src/html-page/client.js b/examples/basic/src/html-page/client.js
@@ -0,0 +1 @@
+console.log('html pages can have their own client bundles too!')
diff --git a/examples/basic/src/html-page/html-sub-page/page.html b/examples/basic/src/html-page/html-sub-page/page.html
@@ -0,0 +1,3 @@
+<p>
+  You can nest html pages like any other pages.
+</p>
diff --git a/examples/basic/src/html-page/md-sub-page/README.md b/examples/basic/src/html-page/md-sub-page/README.md
@@ -0,0 +1,3 @@
+# Markdown sub page
+
+This page is a markdown page that is a sub-page of an html page.
diff --git a/examples/basic/src/html-page/page.html b/examples/basic/src/html-page/page.html
@@ -0,0 +1,21 @@
+<p>
+  The <pre>page.html</pre> page type is the simplest type of page and is minimally processed.
+</p>
+
+<p>
+  The markdown page also supports most <pre>html</pre> content, but some pages
+  benefit the lack of flexibility markdown offers, and offers clarity by just building with html.
+</p>
+
+<p>
+  You can nest pages inside of an html page:
+  <ul>
+    <li>
+      <a href="./html-sub-page/">Html sub page</a>
+    </li>
+    <li>
+      <a href="./md-sub-page/">md sub page</a>
+    </li>
+  </ul>
+
+</p>
diff --git a/examples/basic/src/html-page/style.css b/examples/basic/src/html-page/style.css
@@ -0,0 +1,5 @@
+/* html pages can also have their own style bundles */
+
+.html-page-class {
+  background-color: red;
+}
diff --git a/examples/basic/src/js-page/client.js b/examples/basic/src/js-page/client.js
@@ -0,0 +1 @@
+console.log('This client script runs on the js page')
diff --git a/examples/basic/src/js-page/loose-assets/bare-md-page.md b/examples/basic/src/js-page/loose-assets/bare-md-page.md
@@ -0,0 +1,3 @@
+# Bare MD page
+
+You can have bare md pages inside of a js page as well.
diff --git a/examples/basic/src/js-page/loose-assets/client.js b/examples/basic/src/js-page/loose-assets/client.js
@@ -0,0 +1,3 @@
+import sharedData from './shared-lib.js'
+
+console.log(sharedData.shared)
diff --git a/examples/basic/src/js-page/loose-assets/local-import.css b/examples/basic/src/js-page/loose-assets/local-import.css
@@ -0,0 +1,8 @@
+/*
+  You can keep loose css files anywhere in the src directory, and import them
+  into any page style.css files that need them.
+ */
+
+.a-random-class {
+  background: red;
+}
diff --git a/examples/basic/src/js-page/loose-assets/page.js b/examples/basic/src/js-page/loose-assets/page.js
@@ -0,0 +1,22 @@
+import { html } from 'uhtml-isomorphic'
+
+import sharedData from './shared-lib.js'
+
+export default async function JSPage () {
+  return html`
+  <p>
+    You can keep loose assets basically anywhere in the <pre>src</pre> directory.
+    If they are css or js files, they get included into the built website into any of the
+    client bundle they are imported into.
+  </p>
+  <p>
+    This page demonstrates that with the shared-lib.js and local-import.css files
+    that get imported into the page.js, client.js and style.css files for this page.
+  </p>
+  <p>${sharedData.shared}</p>
+  `
+}
+
+export const vars = {
+  title: 'JS Page with loose assets'
+}
diff --git a/examples/basic/src/js-page/loose-assets/shared-lib.js b/examples/basic/src/js-page/loose-assets/shared-lib.js
@@ -0,0 +1,6 @@
+// js library files can live anywhere in the src directory, and they are only included
+// when a js page or client bundle imports them.
+
+export default {
+  shared: 'data'
+}
diff --git a/examples/basic/src/js-page/loose-assets/style.css b/examples/basic/src/js-page/loose-assets/style.css
@@ -0,0 +1,2 @@
+@import './local-import.css'
+
diff --git a/examples/basic/src/js-page/nested-md-page/README.md b/examples/basic/src/js-page/nested-md-page/README.md
@@ -0,0 +1,3 @@
+# Nested MD page
+
+You can of course nest markdown or html pages inside of a js page. 
diff --git a/examples/basic/src/js-page/page.js b/examples/basic/src/js-page/page.js
@@ -0,0 +1,29 @@
+import { html } from 'uhtml-isomorphic'
+
+export default async function JSPage ({
+  siteName,
+  title
+}) {
+  return html`
+  <p>The js page is the only page type that can render the body with the set varibles.</p>
+
+  <p>
+    All you have to do is export a default function (async or sync) that returns a string, or any
+    type that your layout can handle.
+    In this case, we are using <a href="https://ghub.io/uhtml-isomorphic"><pre>uhtml-isomorphic</pre></a>.
+  </p>
+
+  <p>Here we access the <pre>siteName</pre> and <pre>title</pre> variables inside the page</p>
+
+  <p>${siteName}</p>
+  <p>${title}</p>
+
+  <p>JS pages can also have a page scoped <pre>client.js</pre> and <pre>style.css</pre>. It
+   is an incredibly flexible page type.
+  </p>
+  `
+}
+
+export const vars = {
+  title: 'JS Page'
+}
diff --git a/examples/basic/src/js-page/style.css b/examples/basic/src/js-page/style.css
@@ -0,0 +1,3 @@
+.js-page-class {
+   background: purple;
+}
diff --git a/examples/basic/src/loose-file.md b/examples/basic/src/loose-file.md
@@ -0,0 +1,8 @@
+---
+title: Loose Markdown Title Override
+---
+# Loose Markdown
+
+Loose markdown are markdown files that are **not** named `README.md`.
+
+A loose markdown file named `foo.md`, builds into `foo.html`, in whatever directory it lives in. They don't get a page level `client.js` file, or `style.css` file, but you can set variables in the markdown frontmatter (as seen above).
diff --git a/examples/basic/src/md-page/README.md b/examples/basic/src/md-page/README.md
@@ -0,0 +1,27 @@
+# Nested Markdown
+
+A page folder with a `README.md` markdown file renders to an `index.html` file inside the parent folder.
+
+For example:
+
+```
+/md-page/README.md ---> /md-page/index.html
+```
+
+They can link to other markdown files, and the links are correctly built to their html equivalent.
+
+Page folder markdown file can utilize the following page scoped files:
+
+- [`client.js`](./client.js)
+- [`style.css`](./style.css)
+- [`page.vars.js`](./page.vars.js)
+
+All assets in the `src` directory are copied over to the `dist` folder, 1:1.
+It's a good idea to co-locate images near the document they live in, otherwise
+you end up with a jumble of files in one global images folder.
+It's worth the overhead of copying static assets into a build directory in order to gain a simple approach to organzing assets.
+In the future, asset serving may be virtualized during development.
+
+![](./assets/matrix.gif)
+
+
diff --git a/examples/basic/src/md-page/assets/matrix.gif b/examples/basic/src/md-page/assets/matrix.gif
diff --git a/examples/basic/src/md-page/client.js b/examples/basic/src/md-page/client.js
@@ -0,0 +1 @@
+console.log('Somethig that just runs on md-page')
diff --git a/examples/basic/src/md-page/page.vars.js b/examples/basic/src/md-page/page.vars.js
@@ -0,0 +1,8 @@
+// Pages all support a page.vars.js, though its not usually necessary since most
+// pages support some form of in-page variable declaration.
+//
+// Here we see that the title is overridden from the variables file.
+
+export default {
+  title: 'Nested Markdown Title From Var File'
+}
diff --git a/examples/basic/src/md-page/style.css b/examples/basic/src/md-page/style.css
@@ -0,0 +1,4 @@
+/* This style file only loads in the md-page page */
+.page-scoped-selector {
+  background-color: blue;
+}
diff --git a/examples/basic/src/md-page/sub-page/README.md b/examples/basic/src/md-page/sub-page/README.md
@@ -0,0 +1,3 @@
+# Sub page
+
+Pages can nest inside each other of course. They don't have to have their own `style.css` or `client.css` files
diff --git a/examples/basic/src/root.layout.js b/examples/basic/src/root.layout.js
@@ -0,0 +1,38 @@
+// The root.layout.js file must return the rendered page.
+// It must implement the following variables:
+//
+// - children: the string or type that the page returns that represents the inner-content of the page
+// - scripts: an array of urls that should be injected into the page as script tags, type module
+// - styles: an array of urls that should be injected into the page as link rel="stylesheet" tags.
+//
+// All other variables are set on a page level basis, either by hand or by data extraction from the page type.
+
+import { html, render } from 'uhtml-isomorphic'
+
+export default async function RootLayout ({
+  title,
+  siteName,
+  scripts,
+  styles,
+  children
+}) {
+  return render(String, html`
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <meta charset="utf-8">
+        <title>${siteName}${title ? ` | ${title}` : ''}</title>
+        <meta name="viewport" content="width=device-width, user-scalable=no" />
+        ${scripts
+          ? scripts.map(script => html`<script src="${script}" type='module'></script>`)
+          : null}
+        ${styles
+          ? styles.map(style => html`<link rel="stylesheet" href=${style} />`)
+          : null}
+      </head>
+      <body>
+        ${typeof children === 'string' ? html([children]) : children /* Support both uhtml and string children. Optional. */}
+      </body>
+    </html>
+`)
+}
diff --git a/examples/basic/src/style.css b/examples/basic/src/style.css
@@ -0,0 +1,5 @@
+/* This style.css bundle only loads on the root page. */
+
+.some-class {
+  color: blue;
+}
diff --git a/examples/default-layout/package.json b/examples/default-layout/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "default-layout",
+  "version": "0.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "build": "siteup"
+  },
+  "devDependencies": {
+    "@siteup/cli": "../../."
+  },
+  "keywords": [],
+  "author": "Bret Comnes <bcomnes@gmail.com> (https://bret.io/)",
+  "license": "MIT"
+}
diff --git a/examples/default-layout/src/README.md b/examples/default-layout/src/README.md
@@ -0,0 +1,5 @@
+# Default Layout
+
+Siteup ships a default layout when you don't have a `root.layout.js` file in the root
+of your `src` directory.
+