# Install dependencies
npm install
# Initialize sub repos
git submodule init
git submodule update
# Run site for docs or development
npm run develop
GH_TOKEN
GitHub Personal Access TokenYou will need a GH_TOKEN
environment variable for the site to start. The scope can be repo:public
. See Creating a personal access token in GitHub documentation for details.
You can specify the token in your system environment variables on Windows or Linux.
User documentation can be contributed to in the /docs
folder in this repository! It's written in Markdown and follows a very simple format:
xx-cool-docs.md
title: "My Cool Documentation Page Title"
url: /cool-docs
---
Just some neat docs that are super awesome and helpful, this is just Markdown-formatted.
A relative-path image embed:
![screenshot](xx-cool-docs/cool-screenshot.png)
The xx
in the filename helps determine the sort order of the navigation (until we come up with a better structure).
Everything else is taken care of--table of contents, image generation, code embedding, etc.
To embed an image, we recommend creating a corresponding folder next to your documentation file named the same and put images there. Then you can reference them like:
![screenshot](xx-cool-docs/cool-screenshot.png)
This is just a relative path to your image, as simple as that!
You can embed a "note" block element like:
<Note> An info variant note </Note>
<Note variant="warning"> A warning variant note </Note>
<Note variant="error"> A error variant note </Note>
<Note variant="success"> A success variant note </Note>
Note: The blank line after
<Note>
is important to format the body as Markdown. Prettier will handle this for you, if you forget.
To embed an iframe pointing to our Storybook-based examples, use the <Example />
component:
<Example story="id_of_story" />
The story
prop takes the Storybook ID to navigate to.
TODO: Allow embedding just the canvas.
Have a game you've made with Excalibur? Submit a PR! Edit the src/data/showcase.js
file. Upload an image to src/assets/images/showcase
as a PNG. Import it like the other images in
the showcase module.
GH_TOKEN
defined with your GitHub Personal Access Token that has access to excaliburjs orgOnce you've cloned the repository, run the following commands:
# Install dependencies
npm install
# Run site for local development
npm run develop
# Watch for style changes (css)
npm run styles
# Compile API reference documentation for each Excalibur tag
npm run docs
We recommend using the free Visual Studio Code editor since it's easy to use and works on any platform.
For building Semantic UI:
gem install sass
)Windows or Unix-like
npm run build:styles
npm run styles
During local development, you'd open two terminals with npm start
and npm run styles
at the same time. The CI build will ensure any unbuilt styles
are built and deployed so you don't have to remember to compile CSS before commit.
GitHub will automatically compile master
(edge) and any tagged releases. If a release folder already exists, the GitHub release is ignored and the source controlled version is used.
Compiled documentation lives in static/docs/api/[version]
. The documentation generation works by cloning each version of Excalibur and running the npm run apidocs
script. API documentation is generated in ex/[version]/docs/api
and then copied to the corresponding static/docs/api/[version]
folder.
Generating locally
To generate documentation locally, you can run the following command:
# Compile edge (master)
npm run docs
# Compile specific version
npm run docs -- [version]
If a version
is passed, the documentation will build and output to that version's location (static/docs/api/[version]
). Excalibur versions v0.10.0 and prior will not build locally and are already generated.
If the showcase is in Git and can be run in a sub-directory, you can initialize
a submodule in the showcase
directory.
git submodule add {clone url} showcase/{showcase name}
Example:
git submodule add https://github.com/eonarheim/Excalibur-Shmup showcase/shmup
This is how we can include the Shoot 'Em Up demo without maintaining two versions.