Merge pull request #637 from derbyjs/doc-cleanup

[docs] Fixes and style improvements for GitHub Pages doc site

README.md

@@ -8,7 +8,9 @@ Derby includes a powerful data synchronization engine called Racer that automati
 
 Derby applications load immediately and can be indexed by search engines, because the same templates render on both server and client. In addition, templates define bindings, which instantly update the view when the model changes and vice versa. Derby makes it simple to write applications that load as fast as a search engine, are as interactive as a document editor, and work offline.
 
-See docs here: **http://derbyjs.com/**
+See docs here: **https://derbyjs.github.io/derby/**
+
+Main site: **https://derbyjs.com/**
 
 Examples here: **https://github.com/derbyjs/derby-examples**
 

docs/README.md

@@ -1,8 +1,10 @@
-These docs are built with Jekyll and served on GitHub Pages.
+These docs are built with Jekyll using the [Just the Docs theme](https://just-the-docs.com/).
+
+They are served on GitHub Pages at [https://derbyjs.github.io/derby/](https://derbyjs.github.io/derby/).
 
 # Locally building and viewing docs
 
-Jekyll has a dev server, which will auto-build the docs upon any changes to the source Markdown files. Only changes to `_config.yml` require a dev server restart.
+Jekyll has a dev server, which will auto-build the docs upon any changes to the docs' source files. Only changes to `_config.yml` require a dev server restart.
 
 ## With local Ruby
 
@@ -18,7 +20,7 @@ Run the dev server:
 bundle exec jekyll serve
 ```
 
-The site is viewable at `http://localhost:4000/`.
+The site is viewable at `http://localhost:4000/derby/`.
 
 ## With Ruby in Docker container
 
@@ -28,17 +30,17 @@ One-time container creation:
 docker run --name derby-docs-ruby -v "$(pwd)/docs:/derby-docs" -p 127.0.0.1:4000:4000 ruby:2.7 bash -c 'cd derby-docs && bundle install && bundle exec jekyll serve -H 0.0.0.0 -P 4000 --trace'
 ```
 
-The site is viewable at `http://localhost:4000/`.
-
-Explanation of flags:
-* `-v` - Set up a Docker bind mount, mapping the host's `$PWD/docs` directory to a container directory `/derby-docs`.
-* `-p` - Map the host's local port 4000 to the container's port 4000, to allow the dev server inside the container to serve requests issued against the host.
-* `-H 0.0.0.0 -P 4000` - Have the dev server listen to connections from outside the container. This won't allow connections from outside the host.
-
 Subsequently, to run the dev server:
 
 ```
 docker start -i derby-docs-ruby
 ```
 
+Either way, the site is viewable at `http://localhost:4000/derby/`.
+
+Explanation of flags:
+* `-v` - Set up a Docker bind mount, mapping the host's `$PWD/docs` directory to a container directory `/derby-docs`.
+* `-p` - Map the host's local port 4000 to the container's port 4000, to allow the dev server inside the container to serve requests issued against the host.
+* `-H 0.0.0.0 -P 4000` - Have the dev server listen to connections from outside the container. This won't allow connections from outside the host.
+
 To recreate the container with a different command or setup, run `docker rm derby-docs-ruby` to delete the container first.

docs/_config.yml

@@ -38,6 +38,7 @@ gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into t
 markdown: kramdown
 # remote_theme: just-the-docs/just-the-docs
 theme: just-the-docs
+color_scheme: derby-light # just-the-docs theme customization
 permalink: /:path/:name
 
 # Front matter defaults

docs/_sass/color_schemes/derby-light.scss

@@ -0,0 +1,7 @@
+$body-background-color: #fffcfa;
+$link-color: #107f7d;
+$sidebar-color: #fdf7f4;
+
+.main a:not([class]) {
+  text-decoration-color: #c6e6e6;
+}

docs/_sass/custom.scss

@@ -1,3 +1,7 @@
+// TODO - This default custom scss file appears to be unused by just-the-docs.
+// Custom styles are actually defined in ./custom/custom.scss instead.
+// Can this safely be removed?
+
 /**
  * Add call-out support: https://github.com/pmarsceill/just-the-docs/issues/171#issuecomment-538794741
  */

docs/_sass/custom/custom.scss

@@ -0,0 +1,27 @@
+// Derby template examples use "jinja" as the language with some style customizations,
+// as Derby's template syntax doesn't fully match that of Handlebars. Jinja formatting
+// with some style tweaks looks better than Handlebars, so we use Jinja.
+.language-jinja {
+  .highlight {
+    // Override Name.Attribute and Name.Builtin to use normal text color
+    // instead of being orange.
+    .na, .nv {
+      color: inherit;
+    }
+
+    // Jinja formatting treats double-curlies as italicized Comment.Preproc.
+    // Override to look like Handlebars formatting for double curlies.
+    .cp {
+      // Color from just-the-docs OneLightJekyll keyword color
+      color: #a625a4;
+      font-style: inherit;
+    }
+
+    // Disable syntax error styling for Derby template syntax that
+    // doesn't strictly match Jinja/Handlebars.
+    .err {
+      color: inherit;
+      background-color: inherit;
+    }
+  }
+}

docs/components.md

@@ -6,7 +6,7 @@ has_children: true
 
 # Overview
 
-Components are the building blocks of Derby applications. A component is a view associated with a controller class. The [view](views) is implemented as a Derby template and the controller is implemented as a JavaScript [class](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes) or [constructor function](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Object-oriented_JS). Derby creates an instance of the controller class each time it renders the component view.
+Components are the building blocks of Derby applications. A component is a view associated with a controller class. The [view](../views) is implemented as a Derby template and the controller is implemented as a JavaScript [class](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes) or [constructor function](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Object-oriented_JS). Derby creates an instance of the controller class each time it renders the component view.
 
 
 ## Reuse and organization
@@ -24,7 +24,7 @@ Each component has a scoped model in its own namespace. Data or references to th
 ## Tabs Example
 
 ### index.html
-```derby
+```jinja
 <Body:>
   <view is="tabs">
     <pane title="One">
@@ -37,7 +37,7 @@ Each component has a scoped model in its own namespace. Data or references to th
 ```
 
 ### tabs.html
-```derby
+```jinja
 <index: arrays="pane">
   <ul class="tabs-nav">
     {{each @pane as #pane, #i}}
@@ -112,7 +112,7 @@ module.exports = class Tabs
 
 ## Todos example
 
-```derby
+```jinja
 <Body:>
   <view
     is="todos-new"

docs/components/component-class.md

@@ -71,7 +71,7 @@ Components are Node.js event emitters, so they inherit the `on`, `once`, `emit`,
 >
 > Derby calls this method when removing a component's marker comment from the DOM. `destroy()` emits the `'destroy'` event on the component. Listen for the destroy event in order to implement custom cleanup logic. This method should not be invoked manually.
 
-```derby
+```jinja
 <view is="my-component" on-destroy="handleDestroy()"></view>
 ```
 
@@ -143,7 +143,7 @@ class MyComponent extends Component {
 >
 > Like `component.bind()`, will no longer call back once the component is destroyed, which avoids possible bugs and memory leaks.
 
-```derby
+```jinja
 <my-component:>
   <input as="textInput" value="{{value}}">
 ```
@@ -168,7 +168,7 @@ class MyComponent extends Component {
 >
 > Like `component.bind()`, will no longer call back once the component is destroyed, which avoids possible bugs and memory leaks.
 
-```derby
+```jinja
 <my-component:>
   <input as="textInput" value="{{value}}">
 ```

docs/components/events.md

@@ -23,7 +23,7 @@ If the functions to be called aren't defined on the component, their respective
 ## Custom events
 
 Components support custom events. Dashes are transformed into camelCase.
-```derby
+```jinja
 <modal on-close="reset()" on-full-view="back.fade()"></modal>
 ```
 ```js
@@ -39,7 +39,7 @@ modal.on('fullView', function() {
 ## Emitting events
 Components can emit custom events to be handled by their parents.
 
-```derby
+```jinja
 <index:>
   <modal on-full-view="back.fade()"></modal>
 ```
@@ -57,15 +57,15 @@ Components can emit custom events to be handled by their parents.
 
 ## Calling peer component methods
 
-Components and elements can be set as a property on the current controller with the `as=` HTML attribute ([more detail](../views/template-syntax/paths#controller-properties)). This paired with how controller properties are looked up on function calls makes it easy to connect events on components or elements to methods on other components.
+Components and elements can be set as a property on the current controller with the `as=` HTML attribute ([more detail](../views/template-syntax/view-attributes#as-attribute)). This paired with how controller properties are looked up on function calls makes it easy to connect events on components or elements to methods on other components.
 
-```derby
+```jinja
 <!-- Connecting an instance of a component to an event -->
 <modal as="modal"></modal>
 <button on-click="modal.open()"></button>
 ```
 
-```derby
+```jinja
 <!-- `page` is available on all controllers, even in separate components -->
 <flash as="page.flash"></flash>
 ...
@@ -76,7 +76,7 @@ Components and elements can be set as a property on the current controller with
 
 Component events implicitly pass through any emitted arguments. These arguments are added after any explicitly specified arguments in the expression.
 
-```derby
+```jinja
 <!-- Will log any arguments emitted by the submit event -->
 <dropdown on-submit="console.log()"></dropdown>
 <!-- Will log 'dropdown' followed by any emitted arguments -->

docs/components/lifecycle.md

@@ -103,7 +103,7 @@ Since singleton components do not have a model, only attribute paths may be used
 
 When a component is used many times on a page, such as a repeated item in a list or a commonly used UI element, it is best to write it statelessly for better performance. View partials are the most lightweight, singleton components allow use of custom JavaScript, and full components have their own model state.
 
-```derby
+```jinja
 <user-icon:>
   <div class="user-icon">
     {{getInitials(@user.fullName)}}

docs/components/scope.md

@@ -12,7 +12,7 @@ Each component instance has its own scoped model, providing it isolation from mo
 
 The most direct way to get data into a component is to pass in a reference or a literal as a view attribute.
 
-```derby
+```jinja
 <Body:>
   <view is="user-list" data="{{users}}" num="{{7}}"></view>
 
@@ -32,7 +32,7 @@ See [view attributes](../views/template-syntax/view-attributes) for more informa
 
 There are times when accessing data in the root model is desirable from within the component. This can be achieved both in the template and in the controller.
 
-```derby
+```jinja
 <index:>
   <!-- dynamically look up a user in the users collection -->
   {{#root.users[userId]}}

docs/components/view-partials.md

@@ -13,7 +13,7 @@ While a component's controller is associated with a single view, it can contain
 ## Scope
 By default a view partial inherits the scope where it is instantiated.
 
-```derby
+```jinja
 <index:>
   {{foo}}
   {{with #root.bar as #bar}}
@@ -37,32 +37,20 @@ It is possible to override another component's functionality while preserving it
 If you just want to reuse a view partial the `import` keyword is probably more appropriate. See the [namespaces and files](../views/namespaces-and-files#structuring-views-in-multiple-files) documentation for more details.
 
 
-## Programatic view management
-
-> `view = this.getView(name)`
-> * `name` the name of the view
-> * `view` a template object representing the view
-
-It is possible to access the views in a component's namespace from the controller. This may be used in conjunction with `setAttribute` to override a component's default rendering.
-An example use case would be to set a default template and then allow the user of the component to pass in a template to override the default.
-
-See the [attributes](scope#attributes-vs-model-data) documentation for more information on using `setAttribute`.
-
-
 ## Component tracking
 Derby components are tracked in the DOM with an HTML comment tag. This allows components to be responsible for arbitrary DOM content, for example two table rows that otherwise cannot be wrapped by any other DOM elements.
 
-```derby
+```jinja
 <!-- namespace:component:name -->
 ```
 
 ## Debugging
 
-A relatively quick way to inspect a component for debugging is to find it's comment in the browser's DOM inspector.
+A relatively quick way to inspect a component for debugging is to find its comment in the browser's DOM inspector.
 In modern browsers clicking on the comment allows you to reference it in the console with `$0`.
-Once you have a reference to the comment tag you can access it's controller with `$0.$component` and it's model data with `$0.$component.model.get()`
+Once you have a reference to the comment tag, you can access it's controller with `$0.$component` and its model data with `$0.$component.model.get()`
 
-<img src="/images/docs/charts-debug.png">
+<img src="./charts-debug.png">
 
 ### derby-debug
 There is a plugin which makes accessing your components from the console even more accessible that is recommended for development.

docs/models/backends.md

@@ -7,7 +7,7 @@ has_children: true
 
 # Backends
 
-Racer stores are backed by ShareDB, which is used to persist data, perform queries, keep a journal of all operations, and pub/sub operations and changes to queries. Currently, ShareDB has [two pub/sub adapters](https://github.com/share/sharedb#database-adapters): one for in memory and one for Redis based pub/sub. ShareDB supports in memory or MongoDB storage. The database adapter [ShareDBMongo](https://github.com/share/sharedb-mongo)
+Racer stores are backed by ShareDB, which is used to persist data, perform queries, keep a journal of all operations, and pub/sub operations and changes to queries. Currently, ShareDB has [two pub/sub adapters](https://share.github.io/sharedb/adapters/pub-sub): one for in memory and one for Redis based pub/sub. ShareDB supports in memory or MongoDB storage. The database adapter [ShareDBMongo](https://github.com/share/sharedb-mongo)
 is backed by a real Mongo database and full query support. ShareDB is written with support for additional database adapters in mind.
 
 Getting started with a single-process server and MongoDB:
@@ -51,8 +51,8 @@ collection.documentId.documentProperty
 ShareDB Mongo will add the following properties to Mongo documents for internal use:
 * `_m.ctime` - Timestamp when the ShareDB document was created
 * `_m.mtime` - Timestamp when the ShareDB document was last modified
-* `_type` - [OT type](https://github.com/share/sharedb#data-model)
-* `_v` - [Snapshot version](https://github.com/share/sharedb#data-model)
+* `_type` - [OT type](https://share.github.io/sharedb/types/)
+* `_v` - [Snapshot version](https://share.github.io/sharedb/api/snapshot)
 
 In addition to `ctime` and `mtime`, custom metadata properties can be added to `_m` with middleware that modifies `snapshot.m` in apply or commit.
 

docs/models/events.md

@@ -28,7 +28,7 @@ _Introduced in [[email protected]](https://github.com/derbyjs/racer/releases/tag/v0.9.
 
 > `eventCallback(event, captures)`
 > * `event` - _Object_ - An instance of an Event object (see below)
-> * `captures` - _Array<string | string[]>_ - The captured path segments, one item per wildcard in the pattern. Each `'*'` results in a string, and a `'**'` results in a sub-array of strings.
+> * `captures` - _Array<string \| string[]>_ - The captured path segments, one item per wildcard in the pattern. Each `'*'` results in a string, and a `'**'` results in a sub-array of strings.
 
 Event objects:
 

docs/models/filters-sorts.md

@@ -44,7 +44,7 @@ If `model.filter()` is called with `null` for the function, it will create a lis
 
 There are two default named functions defined for sorting, `'asc'` and `'desc'`. These functions compare each item with Javascript's less than and greater than operators. See MDN for more info on [sorting non-ASCII characters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Sorting_non-ASCII_characters).
 
-You may define functions to be used in `model.filter()` and `model.sort()` via [`model.fn()`](functions#named-functions).
+You may define functions to be used in `model.filter()` and `model.sort()` via [`model.fn()`](reactive-functions#named-functions).
 
 A filter may have both a filter function and a sort function by chaining the two calls:
 

docs/models/reactive-functions.md

@@ -13,7 +13,7 @@ Reactive functions may be run any number of times, so they should be [pure funct
 To execute a model function, you then call `model.start()` or `model.evaluate()`.
 * `evaluate()` runs a function once and returns the result.
 * `start()` also sets up event listeners that continually re-evaluate the
-* function whenever any of its input or output paths are changed.
+  function whenever any of its input or output paths are changed.
 
 > ```
 > value = model.start(path, inputPaths, [options], fn)
@@ -25,9 +25,9 @@ To execute a model function, you then call `model.start()` or `model.evaluate()`
 > value = model.evaluate(inputPaths..., [options], fn)
 > ```
 >
-> * `path` - _string | ChildModel_ - The output path at which to set the value,
+> * `path` - _string \| ChildModel_ - The output path at which to set the value,
 >   keeping it updated as input paths change
-> * `inputPaths` - _Array<string | ChildModel>_ - One or more paths whose values
+> * `inputPaths` - _Array<string \| ChildModel>_ - One or more paths whose values
 >   will be retrieved from the model and passed to the function as inputs
 > * `options` - _Object_ (optional)
 >   * `copy` - Controls automatic deep copying of the inputs and output of the
@@ -61,7 +61,7 @@ To execute a model function, you then call `model.start()` or `model.evaluate()`
 >       that does a `model.get()` on the output path or any paths downstream
 >       of the output, since changes to an input path won't immediately result
 >       in the output being updated.
-> * `fn` - _Function | string_ -  A function or the name of a function defined
+> * `fn` - _Function \| string_ -  A function or the name of a function defined
 >   via `model.fn()`
 >   * The function gets invoked with the values at the input paths, one input
 >     per argument, and should return the computed output value.

docs/models/refs.md

@@ -59,7 +59,7 @@ Racer also supports a special reference type created via `model.refList`. This t
 > `model.removeRefList(path)`
 > * `path` The location at which to remove the reference
 
-Note that if objects are inserted into a refList without an `id` property, a unique id from [`model.id()`](#guids) will be automatically added to the object.
+Note that if objects are inserted into a refList without an `id` property, a unique id from [`model.id()`](paths#guids) will be automatically added to the object.
 
 ```js
 // refLists should consist of objects with an id matching

docs/routes.md

@@ -19,7 +19,7 @@ Routes map URL patterns to actions. Derby routes are powered by [Express](https:
 >
 > * `callback`: Function invoked when a request for a URL matching the appropriate HTTP method and pattern is received. Note that this function is called both on the server and the client.
 >
-> * `page`: Object with the methods [`page.render()`](#pagerender)  and `page.redirect()`. All app routes should call one of these two methods or pass control by calling `next()`.
+> * `page`: Object with the methods [`page.render()`](#page) and `page.redirect()`. All app routes should call one of these two methods or pass control by calling `next()`.
 >
 > * `model`: Derby model object
 >
@@ -37,7 +37,7 @@ Unlike Express, which provides direct access to the `req` and `res` objects crea
 
 > `page.render ( viewName )`
 >
-> * `viewName`: The name of the view to render, see [Namespaces and files](../views/namespaces-and-files) for more details.
+> * `viewName`: The name of the view to render, see [Namespaces and files](./views/namespaces-and-files) for more details.
 >
 >
 > `page.renderStatic ( statusCode, content )`
@@ -57,7 +57,7 @@ Unlike Express, which provides direct access to the `req` and `res` objects crea
 
 ### Middleware
 
-It is possible to directly use [express middleware](https://expressjs.com/guide/using-middleware.html) and get access to a [Racer model](../models#methods).
+It is possible to directly use [express middleware](https://expressjs.com/guide/using-middleware.html) and get access to a [Racer model](./models#methods).
 
 
 ## History