Welcome to the Fictionlab documentation repository. This documentation is built using Docusaurus 3, a modern static website generator.
Ensure the following tools are installed on your local machine:
- Code editor (Visual Studio Code is recommended)
- Node.js
- Yarn 1.22.22 (Classic)
- Git
- A web browser
Tip
When opening this project in VS Code, you should be prompted to install the recommended extensions. If not, you can install them from the list below.
To clone the repository, execute the following command in your terminal:
git clone https://github.com/fictionlab/docsAlternatively, use the VS Code command palette:
> git clone
and paste the repository URL.
By default, development branch is selected. To create new branch see
Updating the Documentation.
After cloning the repository, open the folder in VS Code and run:
yarn install
To start the development environment, use:
yarn start
A new browser tab will open at http://localhost:3000, reflecting any changes made to the files.
To create an entirely new page, create a new .mdx file in the desired folder
within the repository. Docusaurus maps the file structure relative to the
/docs folder into web URLs.
For example: /docs/leo-rover/specification.mdx is translated to
https://docs.fictionlab.pl/leo-rover/specification.
Tip
To avoid including the document name in the URL (e.g., creating a leo-rover page), name the document the same as the parent folder.
Alternatively, you can name it index.mdx. For more information see: Doc URLs - Docusaurus.io.
To update the documentation, clone this repository and create a new branch from
development (or any other branch). For example, to create a branch named
feature/new-button from development:
git checkout -b feature/new-button development
Make necessary modifications and test everything using the development environment. For guidelines on styling and formatting, refer to our Documentation style guide - Documentation guidelines.
Tip
For more information on Docusaurus, visit docusaurus.io.
After making changes, test the compiled code in the browser.
Important
Always test your edits on both desktop and mobile browsers.
Use developer tools to simulate mobile views (press F12 and select Toggle device emulation in Chrome-based browsers).
Finally, check the spelling and formatting:
yarn formatcheck
This will list files requiring formatting changes, which you can fix manually. To fix formatting automatically, use:
yarn format
Caution
Prettier has limited support for MDXv3. Automatic formatting can sometimes create unexpected results.
For more details, see docusaurus.io - usage with prettier
If using
Prettier
extension, you can also use Prettier to only format current document. To do
this, in VS Code use Shift+Alt+F shortcut or type > Format document into
search bar.
To check spelling, run:
yarn spellcheck
This will list unrecognized words in markdown files, which you must correct manually.
Tip
If you use the Code Spell Checker extension in VS Code, documents will be spell-checked in real-time. Any unrecognized words will be displayed in the PROBLEMS tab of VS Code.
Sometimes, CSpell will mistakenly mark correct words as unknown, including custom names like ROS topics and variables. To remove this error, add the word to the CSpell configuration. Right-click the word and select Spelling > Add words to the CSpell configuration. This can be done either in the editor or in the PROBLEMS tab of VS Code.
In the editor, you can use the VS Code shortcut Ctrl+. to bring up the Quick Fix menu, which provides the same options as mentioned above.
When ready, push your changes using:
git push
Tip
For more information on using Git, see Atlassian Git Tutorial.
After pushing changes, create a Pull Request to merge them into the
development branch. Your code will be reviewed by the Fictionlab team. Default
reviewers are:
Warning
Pull requests to the production branch from any branch other than development will not be merged.
Follow these naming conventions for branches:
/feature/description- for new features, components etc./content/description- for markdown content updates/fix/description- for fixes/chore/description- for dependency updates
To report documentation issues, create an issue on this repository or email us at [email protected].