This is a template to quickly create go-along tutorials. The site generates a static webpage with guidance panes on the right and a working area on the left. The working area's functionality is not part of the site. Rather, you specify an URL in the app.config.js file and any backing service is included via the <iframe> tag.
| File | Description |
|---|---|
app.config.js |
Contains configuration of the app including the series of Guide panes |
pages/guidance |
Guidance pages (one .mdx page per pane) should be stored here |
public |
Static assets such as images |
For demonstation purposes, this repository provides a docker-compose environment with a simple terminal backend:
docker-compose upThe lab is then accessible through http://localhost:3030
The environment consists of three containers:
| Container | Ports | Purpose |
|---|---|---|
web |
8080 | Runs node.js serving a production build of the site |
wetty |
10000 | Wetty is a separate project providing a web terminal |
backend |
A simple ubuntu container providing a sample backend |
Communication between wetty and the backend happens via ssh.
The site uses Next.js as web framework.
First, run the development server:
npm run dev
# or
yarn devIf running in development mode for the first time, you will need to install the required modules with
yarn installOpen http://localhost:3000/lab with your browser to see the result.
Note that the lab can be compiled to static content and hosted on any http server or s3 etc. The route to access the lab changes in such scenarios to http://server-url/lab.html.
The app.config.js file contains the configuration of the site. There you can adjust title, description, etc. and define the flow of your guide panes. Only configured guide panes will be part of the tutorial
The template provides a landing page. You can start editing the page by modifying pages/index.js. The page auto-updates as you edit the file.
The template is meant to be hosted statically. But if your tutorial requires dynamic data or an API, you can use the corresponding features from Next.js.
A sample hello API route can be accessed on http://localhost:3000/api/hello. This endpoint can be edited in pages/api/hello.js.
The pages/api directory is mapped to /api/*. Files in this directory are treated as API routes instead of React pages.
Note that APIs only work if deployed on a Node.js server.
Place all content into pages/guidance. The site works well with Markdown files (ending .md) as well as .mdx files, which also provide the ability to include React and HTML components.
Before you develop custom components, read the Next.js docs and make sure you understand how the system works. Especially, the parts about pre-rendered content are of interest.