docs resource allows the creation of Documentation and Tutorials that can accompany your blueprints. Docs allow you to
author your documentation in markdown and give you the ability to embed terminals right into your documentation that point
to the resources in the blueprint.
The following example shows a simple resource that creates a documentation website with two pages
shipyard run command is executed and the
docs resource has been created Shipyard will make the pages defined
by this resource available at
The page shown in the image below was created using the following markdown:
Every page has front matter header that contains the
title and the
id for the page.
id is what is referenced in the
index_pages parameter of the
docs resource shown previously.
To add terminal windows to your documentation you can use the Shipyard docusaurus extension, the following example shows how you could add an interactive terminal for the
docs resource to your documentation.
Any resource that has the capability to host a TTY shell can be targeted by the
Terminal markdown element.
For more information on the markdown authoring capabilities please checkout out the documentation in Docusaurus https://v2.docusaurus.io/docs/creating-pages.
For more information on terminal windows please see the Shipyard documentation below.
port that the documentation will be accessible on your local machine.
Required: false Default: false
open_in_browser is set to true, Shipyard will automatically open the Documentation in your browser.
The path to the markdown pages and static assets used by the documentation.
The title in the left navigation for your documentation.
The index of pages used by your documentation, this is used to build the left hand navigation. The contents of this list should contain the unique
id as specified in the front matter of your markdown page.
Shipyard documentation allows you to embed terminal windows for running resources or the client where the Shipyard binary is running.
When you start a blueprint with
shipyard run shipyard runs a small daemon in the background containing a small server that allows the website created by
docs resources to communicate with the local or remote terminal.
To target a Shipyard resource you use the fully qualified name for that resource as it would be accessible in your browser. For example if you have
docs resource called
mydocs, the fully qualified name would be
In addition to targeting Shipyard resources it is possible to create a shell to the local machine running Shipyard by specifying
Local terminals are compatible with Mac/Linux and Windows platforms.
Powershell.exe depending on OS
Specify the shell to run for the terminal. When targeting a remote resource this value defaults to
local terminals this value defaults to
/bin/bash for Linux/Mac and
Powershell.exe for Windows.
Specify the working directory for the terminal.
Default: terminal default
Specify a user to run the terminal as.
When this tag is present the terminal will be initially shown in the collapsed state.