dojo / site

Documentation site for https://github.com/dojo/framework

dojo.io

Documentation website for Dojo.

• Running dojo.io Locally
• Build Time Renderer (BTR)
• Code Splitting
• Content Pipeline
  • Markdown Compiler
  • Available Widgets
    • Alert
    • Aside
    • CodeBlock
    • CodeSandbox
  • Adding New Widgets
• Adding Content
  • Blog Post
  • Tutorial
  • Reference Guide
  • Roadmap Entry
• Tests
• Now Deployments

Running dojo.io Locally

Before building for the first time, run npm install.

To build, serve and watch, run npm run build:dev. Open http://localhost:9999/, the page will reload on any changes.

Build Time Renderer (BTR)

dojo.io is built using the Build Time Renderer, part of the dojo build process, to statically render each route as html and css only. During the build process, after the site is built, each route is loaded up in JSDom, a snapshot is taken, and an index.html is generated. This allows pages to be loaded in full, quickly and without javascript.

No javascript is served to the user.

Code Splitting

Each route should have its own unique Outlet in the App.tsx file and that Outlet should point to a unique widget for the route. If you are using the content pipeline to dynamically build your pages (aka you are using the Section or Page widgets) a wrapper widget may be required to accomplish this requirement (example: TutorialsPage and TutorialsLanding).

Content Pipeline

In Dojo 5, a new feature was introduced to the Build Time Renderer called Blocks. Blocks allow us to run nodejs code during the BTR process, cache the results in the javascript output, and render them in the client. This forms the basis of the content pipeline.

The site's Blocks can be found under src subdirectories, labeled with a .block.ts extension.

Markdown Compiler

The markdown compiler takes the contents of a mardown file as an input. The input is then run through remark, which converts it to HTML and looks for specially designated tags to convert to Dojo widgets. This is used for generating entire pages from markdown.

Available Widgets

The available dojo widgets are defined in src/common/markdown.ts file as handlers.

Alert

The Alert renders a section of text with a colored left border. It takes an optional type parameters.

Types

• info (default)
• success
• warning
• danger

Default sample

[Alert]
Create a new root node for the application
[/Alert]

Warning sample

[Alert type=warning]
Create a new root node for the application
[/Alert]

Aside

The Aside widget takes a title parameter, and renders a card with a title and body text. The widget has a black background with an orange left border.

Sample

[Aside title="Mandatory object for properties"]
The 2nd argument of the `w()` function is mandatory even you have no properties to pass in. This is to ensure the correct type guarding for all widgets in TypeScript.
[/Aside]

CodeBlock

The CodeBlock widget takes two requires parameters (path and language) and one optional parameter (region).

• path - The path, relative to the content folder, of a file to parse.
• language - The language to use for code highlighting.
• region - (Optional) A defined region within the file to grab. If not provide, the entire file's contents will be returned.

CodeBlock from file sample

[CodeBlock path=tutorial-2-finished/src/App.tsx, language=tsx]

CodeBlock from file with region

[CodeBlock path=tutorial-2-finished/src/App.tsx, region=render, language=tsx]

Designating a region

Defining a region in a file varies by language. The region comments will never appear in a codeblock, as they are stripped out during the parsing.

• ts
  • Start Region: // @start-region render
  • End Region: // @end-region render
• tsx
  • Start Region: // @start-region render
  • End Region: // @end-region render
• html
  • Start Region: <!-- @start-region render -->
  • End Region: <!-- @end-region render -->
• css
  • Start Region: /* @start-region render */
  • End Region: /* @end-region render */
• json
  • Start Region: // @start-region render
  • End Region: // @end-region render

CodeSandbox

The CodeSandbox widget takes a url parameter, and renders an embedded codesandbox on the page using the provided URL.

Sample

[CodeSandbox url=https://codesandbox.io/embed/github/dojo/examples/tree/master/todo-mvc]

Adding New Widgets

You can add any Dojo widget to the handlers list by following the steps below.

1. Add your widget to the handlers list in the src/common/markdown.ts file.
   • Simple widgets (no child content) can be designated as inline widgets. These must be written on one line in the markdown and don't need a closing tag.
     • Example: { type: 'CodeSandbox', inline: true }
   • Widgets with child content should be multi-line widgets. These must be written on multiple lines with opening and closing tags on their own lines.
     • Example: { type: 'Aside' }
2. Define your widget with its handle in the src/main.tsx file.
   1. Import your widget into the file.
   2. Define your widget in the registry: registry.define('docs-alert', Alert);
      • The handle to use is the lowercase version of the name you put in handlers with docs- added to the front.
3. (Optional) If your widget needs custom parsing logic (example: CodeBlock), you can add a widget creation function to the widgets list in the src/common/markdown.ts file. Use the handle you put in main.tsx to register your widget creation function.

Adding Content

Blog Post

1. Add a markdown file to the content/blog/en folder, in the following format.

   content/blog/en/new-post.md

   ---
   title: New Post
   date: 2019-03-22T12:00:00.000Z
   author: The Author
   ---
   ## New Post
   
   The description to show on the blog index page.
   
   ![The image for the blog](/assets/blog/title-of-blog/featured.png)
   <!-- more -->
   
   ## Another header in the blog after the break
   
   More content for the blog after the break

Tutorial

Coming soon.

Reference Guide

1. Reference Guides should be added to the repository of the referenced content (most likely dojo/framework).

   The reference guide should consist of the following files:

   • introduction.md
   • supplemental.md

   These files should appear in docs/:locale:/guide-name/ in the repository.

   Pages will be generated for the introduction and basic usage files, and one page for each top level header (h1) in the supplemental file.

2. Add the guide to the GUIDES list in the src/constants.ts file. Each guide has the following parameters:

   • name - Used in navigation
   • directory - (Optional) The name of the directory holding the guides. Defaults to name.toLowerCase().replace(' ', '-')
   • repo - (Optional) GitHub repository where the guide is located. Defaults to dojo/framework
   • branch - (Optional) Repository branch where the guide is located. Defaults to the latest framework branch.

Roadmap Entry

Add a markdown file to the content/roadmap/en folder, in the following format.

content/blog/en/new-post.md

---
title: Dojo 6
date: Q2 2019
released: false
---

Features coming in Dojo X

- A feature
- A shiny feature
- A shinier feature
- The shiniest feature

Dates

Dates in the roadmap section can be of two formats:

1. Quarter format. Example: Q2 2019, Parsed Value: June 30, 2019 23:59 GMT
2. Month format. Example: January 2019, Parsed Value: January 31, 2019 23:59 GMT

The entries will be sorted by the parsed date. If the date cannot be parsed, it will be sorted to the top of the roadmap.

Tests

We use Jest for unit tests on the site.

Run all unit tests, npm run test or npm test or jest.

Now Deployments

On submission of a PR, an automatic deployment of the site is made to now.sh. The PR will be updated with the URL to the deployment automatically. You can test this deployment prior by running now locally (install the now cli with npm install -g now).

Switching Versions

On a major version change, the following steps should be followed to archive the old site and update to the new version. All changes for the upcoming version can (and should) be merged into master ahead of time so they are deployed to https://next.dojo.io/ for testing before the switch.

As part of this process you will be creating a new branch for the upcoming version. Master is always next, current should be in a versioned branch, like v7. For the sake of this example, v7 will be the upcoming version and v6 will be the previous "current" version.

Version	Version Number	Current Domain	New Domain After Update
Current Version	v6	dojo.io	v6.dojo.io
Upcoming Version	v7	next.dojo.io	dojo.io

1. Update the deploy.sh script to include the upcoming version's (v7) branch as a "production" branch. NOTE: Do not create the branch yet. (Example PR: #220)

   PROD_BRANCHES=("master" "v6" "v7")

2. In the Travis settings for dojo/site, add an Environment Variable for the current version (v6) branch.

   Name	Value	Branch
   DOMAIN_PREFIX	v6	v6

3. In the current version's (v6) branch, update the footer links (Example PR: #222):
   • Language links should be updated to include the new subdomain (in Footer.tsx)
   • Add a Latest link back to dojo.io
4. Update subdomains for the current version v6.
   1. After the #3 changes are merged, go to dojo project dashboard in now/vercel. Find the newly created projects for the current version (v6). In this case, two new projects were made v6-dojo-io and zh-cn-v6-dojo-io.
   2. In the settings for each, add the appropriate subdomains:

      Project	Subdomain
      v6-dojo.io	v6.dojo.io
      zh-cn-v6-dojo-io	zh-cn.v6.dojo.io

5. Create the branch for the upcoming version (v7).
6. Update the target branches for documentation and examples (Example PR: #221)

After #6 is merged, the v7 branch will now be the new current version and will deploy to dojo.io.

site's Issues

Browser Testing

Page	Chrome	Firefox	Edge	Safari
Home	✔️	✔️	✔️	✔️
Menu / Header	✔️	✔️	✔️	✔️
Blog	✔️	✔️	✔️	✔️
Blog Post	✔️	✔️	✔️	✔️
Reference Guides Landing	✔️	✔️	✔️	✔️
Reference Guides	✔️	✔️	✔️	✔️
Examples	✔️	✔️	✔️	✔️
Playground	✔️	✔️	✔️	✔️
Roadmap	✔️	✔️	✔️	✔️
Community	✔️	✔️	✔️	✔️

Examples

Examples are currently criminally under marketed, they're not listed on dojo.io at all I don't think? It would be nice if they were nicely listed on the with any meta information we can, along with thumbnails (perhaps from codesandbox?), and runnable in codesandbox.
https://github.com/dojo/examples

Community: Supporters, contributors, sponsors, and users

One set of questions people have when they choose any new technology include who supports it, who are the contributors/leaders, who sponsors the project, and who are well known users.

Currently supporters/sponsors would include SitePen, users would include Daimler, Esri, and others (we can ask on Discord for people who want to get listed), and contributors could be a list of people who have submitted PRs, and perhaps a team directory at some point.

Add travis to run tests and build

Make it quick

Parent Menu Item Highlighting in Hamburger Menu

Need to find better option for highlighting parent menu items in the hamburger menu. Currently it is using a lifecycle hook in two place (Header widget and ReferenceGuideMenu widget) to achieve this.

	protected onAttach() {
		const item = this.registry.getInjector<Router>('router');
		if (item) {
			const router = item.injector();
			router.on('outlet', () => {
				this.invalidate();
			});
		}
	}

Discussion so far:

Keeping documentation content up to date

Currently, documentation, such as reference guides, are completely hand-written. Over time, this could become a maintenance challenge as Dojo's features evolve and develop since the guides have to be manually reviewed and updated.

Ideally, critical portions of documentation could be either automatically generated from the source code or supported by some sort of test to ensure that the documentation is still correct.

Please use this issue to record thoughts on the feasibility of this idea as well as capture ideas about how we might be able to implement it.

Document Dojo's TypeScript support

This document should capture the project's approach to supporting older versions of TypeScript and, possibly, its approach to adopting new versions as they are released.

Blog

Once we have the content processing pipeline in place. This should be just a matter of converting the existing content and displaying them in a similar manner as we have today.

Depends on: #16

DGrid wrapper example's preview images not loading

Roadmap

The roadmap is currently buried in community, feels like it should have a higher precedence and be more visual than it currently is?

If we're going to use markdown as the source of truth for this in this repo, it might be a good opportunity to write some fancy macro's and widgets to make this more visual/interactive.

Make it useable without JavaScript

We should progressively enhance the site so that it is functional without JavaScript.

Should be useable without JavaScript

The site shouldn't complete falldown without JavaScript. We should use JavaScript to progressively enhance the site.

Document Dojo's release process

The release process for Dojo needs to be documented so that we can ensure a consistent, reliable, and repeatable process for deploying updates.

Multi-Language Support

• Need language selector with predefined list of languages
• Language string (en, zh, fr, etc) needs to be added to the URLs (URLs should be dynamically added to BTR over using the .dojorc file).
• The selected language should be passed to the blocks.

Relates to #53

Better legibility for body text

The color of the main text is set to #666. Please use something darker, at least #333, to make docs as legible as possible.

Enhanced Playground

Integrating a drop down that allows to select either from examples or some other sample code.

Continuation of #4

Initial site scaffold

Migrate to Now V2

We are using v1 of now, but it will soon be deprecated. We need to migrate to v2, but in order to do that we cannot run the build on now directly (due to how we use puppeteer).

The solution is to run the build on Travisand deploy tonow` from Travis instead of directly from github.

Doc/Tutorial technology

Hey there,

I have a quick question. Do you have a static site generator for the documentation and tutorial portion on your website? Which would that be? Could not find any credit on the pages. It is pretty neat, was just wondering if I could use whatever it is use that you are using, unless it is proprietary stuff.

Enhanced Mobile Menu

Should include sub-content and avoid landing pages on mobile devices. Also removes the need for a side menu on Tutorials / Reference Guides.

Can this site support multiple languages?

I can put translate markdown file here(chinese) if this site support multiple languages.

https://github.com/xiaohulu/cn.dojo.io

RSS generator

We need generate RSS for the blog posts.

Make hamburger menu expandable sections toggle purely with CSS

To allow the hamburger menu to operate without JavaScript (see #71), the toggleable sections need to be converted to pure CSS.

Disable Tutorials Section for Initial Launch

Disable tutorials (remove routes and remove menu item).

Make it work offline

Governance

In order to comply with the new Node+JS Foundation, we need to list our governance structure on the website and in a repo somewhere.

My goal is that Dojo qualifies for the Impact stage, which is outlined at https://github.com/nodejs/bootstrap/blob/master/proposals/stage-2/PROJECT_PROGRESSION/PROJECT_PROGRESSION.md#impact-stage-formerly-top-level

Google analytics

Setup google analytics for dojo.io

Document Dojo's governance process

Document should describe how project is led and how decisions are made

HNPWA example link is bad (leads to 404 error)

• Link on site: https://dojo.github.io/examples/hnpwa/
• Correct link: https://dojo-2-hnpwa-d668d.firebaseapp.com/

Clicking left sidebar link within guide does not jump to top

1. Go to Reference Guides
2. Click on i18n
3. Click on Basic Usage
4. Scroll to bottom
5. Click on Working with message bundles

I would expect that it would scroll to the top of that document, but I remain at the bottom of the page.

Content Pipeline Documentation

Documentation for #16 in README

Playground

For MVP:

• basic full codesandbox editor

Stretch goals:

• Integrating a drop down that allows to select either from examples or some other sample code.

Blog posts do not load on first visit from blog home page

Get testing on IE working

Travis testing is currently running on Edge, Chrome, Firefox and Safari, but not IE. The following error was occurring when IE is added the browserstack setup in the intern.json.

Suite internet explorer 11 on WINDOWS FAILED
Error: Syntax error
  at <webpack:/Destroyable.ts:28:7>
No unit test coverage for internet explorer 11 on WINDOWS
internet explorer 11 on WINDOWS: 0 passed, 0 failed; suite error occurred

Document Dojo's contributor guidelines

Document should describe what levels of contributor are recognized by the project and how someone can attain each one. Should also contain a list of current and emeritus contributors to the project.

Examples page does not load with JavaScript disabled

The CSS does not load properly with JavaScript disabled.

Blog Compatibility Plan [RSS]

We want to make sure that we have a strategy around a seamless compatibility between the old site and the new.

• The URLs to blog posts should be the exact same
• The RSS generated should be the same
• We should try not to spam RSS feeds with all existing posts when the new site goes live.

Deploy to gh-pages/now or similar for staging

Depends on: #15

Version Selector

Starting with the initial release it should be possible to have each Dojo release (at least each major one) have preserved documentation on the website (which will default to the most recent). A selection drop box should be available to select which version you want to see documentation for.

Home Page

Open to experimentation?! Failing that we could port the existing page to use the real intersection meta, create a fancy terminal widget to display the cli stuff use a real custom element for the menu? In general the front page could do with some love.

Community

Basically just the community links off the current community page on dojo.io, perhaps made bigger if the roadmap no longer sits on there?

Reference guide

A lot of our readme content in framework is reference guide like. We should decide how to better split this from the README into discreet chunks and how to display.

Depends on: #16

Scope

During build time / in content pipeline:

• Pull other dojo repos
• Parse specific markdown files from the pulled repo
• Display via Page widget

Document Dojo's LTS policy

Develop and document Dojo's long term support policy.

Content processing pipeline

Go Live Prod Prep

Tasks required for go live

Tasks

• Determine where production environment will be. Now V1
• Setup redirects for current blog posts from old URLs to new URLs.
• Move remaining blog posts over
• Configure pipeline for production (deployment on repo).
  • Deploy from master and record deployment in GitHub deployments
  • Alias master deployment to dojo.io
• Update roadmap with actual content
• Update reference guide summaries/descriptions
• Link for Build with Dojo button on home page from content

Make it responsive

I suggest put the Fontawesome Icons widget to a single git repo

👍 It was great! I found the Fontawesome Icon here.

I suggest put the Fontawesome Icons widget to a single git repo like angular-fontawesome or vue-fontawesome, then I can npm install it to my dojo project. 😄

Thanks!

Tutorials

Depends on: #16

Responsive Menu

Create a responsive menu, similar to what's on the original dojo.io.