HOW TO

Development setup

Initial Setup

• copy .env.template to .env

• set the correct values in .env, namely GITHUB_ACCESS_TOKEN

• get a Github access token from https://github.com/settings/tokens?type=beta with access to https://github.com/needle-tools/needle-engine-support

  • only needs permissions for discussions

Local Development

• open the VS Code workspace

• run npm install

• run npm run start

Adding new pages

• in documentation/.vuepress/config.js add a new entry to the sidebar and navbar

Inject Sample Code

You can automatically include code written in the Needle Engine Samples repository in the documentation. The code for parsing the sample code can be found in documentation/.vuepress/plugins/include-samples-code/index.js

All typescript, javascript and c# code is parsed in the Needle Engine Samples Repository.

Follow these steps to insert code blocks:

1. In the samples repository mark the beginning and end of a sample code block like this. Give each tag a sensible name, for example:

   // START MARKER play_animation_on_trigger`
   <code>
   // END MARKER play_animation_on_trigger

2. Push to the docs/code-marker branch

3. In the documentation repository (this repo) include code blocks by adding a HTML comment in the markdown files. For example:

   <!-- SAMPLE subscribe_to_events -->      

   Note: If your code block doesnt show up check the console of the documentation local server. If you just updated the samples repository it may take a few minutes to be available.

   You can also insert additional markdown inside of the HTML comment. It will then only be rendered if the sample code can be found. For example:

   <!-- SAMPLE disable environment light 
   ## Disable environment light
   -->

   This is looking for a sample marker with "disable environment light" and if it finds it, it will render the markdown in the subsequent rows and then the code