Microsoft Team Labs

The Microsoft Team Labs project is an application for building and hosting Codelabs via a static website.

Codelabs are interactive instructional tutorials, which can be authored using simple formatting conventions and markdown syntax. The application builds Codelabs from markdown files provided, and builds a static website used to display a categorized selection of Codelabs for users to interact with.

How it works

The application uses the following tools and libraries to build the Codelabs and serve the website:

NodeJS

NodeJS is used to manage javascript packages, and to run the Gulp package that builds the application.

Claat tool

Claat (Codelabs as a thing) is a command line tool developed in Go. The program takes an input in the form of a resource location and then converts the input into a Codelab format, HTML by default.

Claat is used by Gulp to convert markdown files into HTML files.

Gulp

Gulp is a javascript package for automating repetitive workflows and composing them into build pipelines.

View the gulpfile.js file in the application home directory to understand all actions that are part of the build pipeline. In summary it performs the following key actions on startup:

• Run the Claat tool to build Codelabs from the provided markdown files
• Builds, minifies and exports HTML, CSS, and Javascript files to the build directory
• Generates and parses metadata set in the Codelabs as JSON to be used by the Swig template engine
• Creates the index.html file from metadata for the Swig template engine to render

User Interface

Swig

The UI uses the Swig template engine to render templates and provide operational logic to the static website. Metadata with Codelab details generated by Gulp can be accessed by Swig as variables to display the Codelabs.

UI Components

UI components from the PolymerElements library are used to provide pre-built UI elements.

Development

Prerequisites

The project requires the following major dependencies:

• Go language
• Node.js v10+ and npm
• claat

With Node installed, run npm install in the root of the repo:

$ npm install

(Optional) npm installs binstubs at ./node_modules/.bin/. When running tasks like gulp, you may want to add ./node_modules/.bin/ to your $PATH for convenience:

$ export PATH="./node_modules/.bin/:$PATH"

This does pose a mild security risk, so please do so at your own risk.

Serve the website

To serve the site in dev mode, run npm run serve. This will compile all the views and Codelabs into the build/ directory and start a web server to serve that content. Additionally, all files will be watched and the site will rebuild when they change.

The output will include the address where the server is running (http://localhost:8000 by default).

You can also serve the completely compiled and minified (prod) version with the npm run serve:dist command. Always run this before publishing, as it will show you a replica of what will appear on staging/production.

Add new Codelabs

To author new Codelabs, follow the guidance set out in this Codelab Formatting Guide or copy one of the existing Codelabs found in the codelabs directory.

New Codelabs added to this directory will be automatically built when the application is run, transforming the markdown file into an HTML file with associated metadata.

When creating new Codelabs, ensure the metadata at the top of the markdown file includes the following:

• id: The name of the folder generated once you export the markdown file via claat e.g. my-codelab
• summary: A short summary of the Codelab that will be shown in the Codelab browser UI
• categories: A single, top-level category that will be used to group Codelabs by platform
• environment: Tag that allows use to output some Codelabs for a specific environment, defaults to web
• status: One or more of (Draft, Published, Deprecated, Hidden)
• authors: Indicate the author(s) of this specific Codelab
• tags: Comma seperated metadata, first tag should be one of (Introduction, Beginner, Intermediate, Advanced) to indicate Codelab skill level

Views

Views are themed/styled collections of Codelabs, served from the same url. Codelab tags are used for selecting Codelabs into views. View definitions are stored in /app/views directory. Views commonly correspond to events (e.g. NEXT 2018) or abstract themes (e.g. Windows), but we refer to them generically as "views" internally.

Only the default view is currently used in the Microsoft Team Labs application.

Add a new view

To add a new view (e.g. to serve Codelabs for a particular event):

1. Create a new folder in app/views, which will be the "view id". As the view id will appear in the URL, it should be lowercase with special characters replaced with dashes.

   // Examples
   My Codelab -> my-codelab
   Learn underscore.js -> learn-underscore-js 
   Tracking with utm_source -> tracking-with-utm_source // URL friendly characters can remain
   

2. Add a new file named view.json inside this folder. Here is a template view.json:

   // app/views/my-event/view.json
   {
     "title": "My Event", // Required: Page and view title.
     "description": "", // Required: Text description of the event.
     "tags": [], // Required: List of string tags by which to include codelabs.
     "categories": [], // Optional: List of string categories by which to include codelabs.
     "customStyle": "style.css", // Optional: name of a custom stylesheet to include.
     "exclude": [], // Optional: List of regular expressions to exclude particular codelabs.
     "catLevel": 0, // Optional: Category level to use for iconography
     "sort": "mainCategory", // Optional: Method for sorting codelabs.
     "pins": [], // Optional: List of codelab IDs that should be "pinned" at the start.
     "ga": "", // Optional: Custom google analytics tracking code. By default, all codelab views are tracked on the main codelab analytics.
     "hidden": false, // Optional: Include view in list of views on home page. Still accessible via direct URL.
   
     // Optional: URL to a custom logo for the codelab. If provided, this logo
     // must be placed in app/views/<view-id>/ and referenced as such.
     //
     // Use SVG logos, or size images to 125px high at 72 DPI
     //
     // Minify images before uploading using a tool like ImageOptim.
     "logoUrl": "/my-event/my-event-logo.svg",
   }

3. (Optional) Add a file named style.css inside the view folder. If provided, this file will be included in the HTML, allowing for custom styles.

   This file is not included in the main assets bundle, so there will be a performance decrease as the browser needs to load additional styles. Furthermore, if the Codelab schema were to change, your custom styles may be broken.

4. (Optional) Add a file named index.html inside the view folder. This allows you to fully customize the view, but comes at the expense of duplication.

5. Execute the serve command as described above to see the view.

Options

--base-url - base URL for serving canonical links. This should always include the protocol (http:// or https://) and NOT including a trailing slash.

--codelabs-dir - absolute or relative path on disk where Codelabs are stored. Any filters will be applied to these Codelabs, and then the resulting selection is symlinked into the build folder. The default value is "." (the current directory).

--codelabs-filter - regular expression by which to filter Codelabs IDs for inclusion. If a filter is not specified, all Codelabs are included.

--codelabs-namespace - URL path where Codelabs will be served in the web server. The default value is "/codelabs", meaning Codelabs will be served at https://URL/codelabs.

--views-filter - regular expression by which to filter included views (events). If a filter is not specified, all views are included.

The following options are only relevant when invoking claat:

--codelabs-env - environment for which to build Codelabs. The default value is "web".

--codelabs-format - format in which to build the Codelabs. The default value is "html"

--codelab-source - Google Doc ID from which to build Codelab. This can be specified multiple times to build from multiple sources.

Testing

To run the tests manually in a browser, execute the following:

$ gulp serve
$ open http://localhost:8000/app/js/all_tests.html

Errors and Troubleshooting

NPM

Error: EPERM: operation not permitted, symlink '..' -> 'build\codelabs'

Run the NPM script under an admin terminal.

Error: Tables aren't correctly formatted

Change the End of Line Sequence from CRLF to LF.

Claat

Error: spawn claat ENOENT

Ensure that the Claat tool has been installed using Go package manager. If you have tried to install but Go package manager does not return a confirmation, try these steps:

• Confirm your Go binaries: Go to your computer’s Control Panel, then to System and Security > System > Advanced system settings, and on the left-hand pane click the Advanced tab. Then click on Environmental Variables on the bottom-right-hand side. Ensure Path under System Variables has the “C:\Program Files\Go\bin” variable in it.
• Create the GOPATH variable: Go back to your Control Panel and navigate to System and then Environmental Variables. Then under System Variables click on New. Next to Variable Name, enter “GOPATH,” and next to Variable Value enter “C:\Projects\Go”.

Gulp

For help documentation/usage of the Gulp tasks, run:

$ gulp -T

If gulp startup times are really slow, try removing node_modules/ or running

$ npm dedupe