How to Edit Wiki

Robonomics Wiki is open source. Any corrections are welcome: fixing errors, typos, some unclear or outdated information, translation into any language. You’ll need a GitHub account.

How to edit

If you need to edit docs of Robonomics Wiki, please, follow these steps

Make sure, you have Node.js installed.

1. Clone repo

At first, you need to clone the wiki repository:

git clone https://github.com/airalab/robonomics-wiki.git

Go to the directory of the repository and run the following commands:

using npm

cd robonomics-wiki
npm install

using yarn

cd robonomics-wiki
yarn install

2. Serve locally (develop, develop-m1)

node version must be 20 || >=22

Then deploy the project locally:

npm run start

may need to create .env file with the same variables as in .env.example file

3. Make PR

Make pull request to wiki repo

Components

CUSTOM COMPONENTS

A tip when adding custom components:
If there is something wrong with the layout after adding a component you might want to check spaces. It should help to REMOVE spaces after opening tag and closing tag (like in example below)

{% roboWikiNote {title:"test", type: "okay"}%} Lorem ipsum dolor sit amet.{% endroboWikiNote %}

Code

You can add helpful extras to your code:

code with copy button

{% codeHelper { copy: true}%}

some text code
	another test line
		something else

{% endcodeHelper %}

or code with additional line

{% codeHelper { additionalLine: "additional line"}%}

some text code
	another test line
		something else

{% endcodeHelper %}

Properties for code-helper

some text code
	another test line
		something else

Frontmatter

Docs in Robonomics Wiki contain frontmatter block. It must be at the top of the Markdown file, and must take the form of valid YAML set between triple-dashed lines. Between the triple-dashed lines, you can set or edit folowing options:

---
title: How to contribute # Title for the page, you do not need to duplicate it in text
contributors: [positivecrash] # Main contributors (who actively curates this page). GitHub nickname required, without any additional symbols
tools:
  - rust 1.62.0
    https://blog.rust-lang.org/2022/06/30/Rust-1.62.0.html
  - Robonomics 1.4.0
  - baxter
    http://wiki.ros.org/melodic/Installation
    # Tools that were used for technology testing
---

Grid

Helps to add grid layout to elements:

• Use grid wrapper component first:

 {% roboWikiGridWrapper %}{% endroboWikiGridWrapper %}

• And then use as many grid items components as you like inside wrapper:

{% roboWikiGridWrapper {columns: '3', align: center} %}
	{% roboWikiGrid %} first element {% endroboWikiGrid %}
	{% roboWikiGrid %} second element {% endroboWikiGrid %}
	{% roboWikiGrid %} third element {% endroboWikiGrid %}
{% endroboWikiGridWrapper %} 

Properties for robo-wiki-grid-wrapper

Raspberry Pi 4 (at least 2 GB RAM)

SD card 16Gb

Zigbee adapter(Optionally)

Zigbee smart devices(Optionally)

Desktop for setup

Images

How to upload

Upload image in folder src/assets/docs/images/url-of-your-doc

• If image needs to be localized, insert all of them in one folder
• Use locale appendix in name of images if it’s localized, e.g. image_en.jpg
• Make sure your image is web optimized and at the same time it looks good

How to insert

There are two ways for inserting pictures in your documents:

It is recommended to insert pictures with built-in tag <robo-wiki-picture>, however you may also use standard way for Markdown files.

with caption

 {% roboWikiPicture {src:"robonomics-lab.png", alt:"explore robomomics wiki", link: '/docs/overview', caption: "EXPLORE"} %}{% endroboWikiPicture %} 

or without caption

 {% roboWikiPicture {src:"robonomics-lab.png", alt:"explore robomomics wiki", link: '/docs/overview'} %}{% endroboWikiPicture %} 

or simple image

 {% roboWikiPicture {src:"robonomics-lab.png", alt:"explore robomomics wiki"} %}{% endroboWikiPicture %} 

or simple image with caption

 {% roboWikiPicture {src:"robonomics-lab.png", alt:"explore robomomics wiki", caption: "EXPLORE"} %}{% endroboWikiPicture %} 

Properties for robo-wiki-picture:

Notes & warnings

You can add notes and give them specific types:

• warning (with image)
• okay (green color)
• note (grey color)

note with title

 {% roboWikiNote {title:"EXAMPLE TITLE", type: "okay"}%} {% endroboWikiNote %} 

note with content

 {% roboWikiNote {type: "okay"}%} Lorem ipsum dolor sit amet.  {% endroboWikiNote %}  

note with title and content

 {% roboWikiNote {title: "TITLE", type: "okay"}%} Lorem ipsum dolor sit amet.  {% endroboWikiNote %} 

Join Discord

Join Robonomics Developers Discord to connect with community and get technical support.

Properties for robo-wiki-note

Tabs

You can add tabs to the doc:

• Use tabs wrapper component:

 {% roboWikiTabs {tabs: [{title: "Linux"}, {title: "OSX"}]} %} {% endroboWikiTabs %} 

• And then use as many tab items components as you like inside wrapper:

{% roboWikiTabs {tabs: [{title: "Linux"}, {title: "OSX"}]} %}
	{% roboWikiTab {border: true} %} ip a {% endroboWikiTab %}
	{% roboWikiTab %} <pre>ifconfig </pre> {% endroboWikiTab %}
{% endroboWikiTabs %}

horizontal tabs

{% roboWikiTabs {tabs: [{title: "Linux"}, {title: "OSX"}]} %}
	{% roboWikiTab %} ip a {% endroboWikiTab %}
	{% roboWikiTab %} ifconfig {% endroboWikiTab %}
{% endroboWikiTabs %}

vertical tabs

{% roboWikiTabs {tabs: [{title: "Linux"}, {title: "OSX"}], mode: 'vertical'} %}
	{% roboWikiTab %} ip a {% endroboWikiTab %}
	{% roboWikiTab %} ifconfig {% endroboWikiTab %}
{% endroboWikiTabs %}

tab item with border

{% roboWikiTabs {tabs: [{title: "Linux"}, {title: "OSX"}] %}
	{% roboWikiTab {border: true} %} ip a {% endroboWikiTab %}
	{% roboWikiTab %} ifconfig {% endroboWikiTab %}
{% endroboWikiTabs %}

Properties for robo-wiki-tabs (wrapper)

Properties for robo-wiki-tab (item)

ifconfig 

Title with anchors

You can create custom titles with anchors and give them certain value

title with anchor

 {% roboWikiTitle { type: 2, anchor: 'test-anchor'} %} Robonomics Wiki {% endroboWikiTitle %} 

or title without anchor

 {% roboWikiTitle { type: 5} %} Robonomics Wiki {% endroboWikiTitle %} 

Robonomics Wiki (custom title)

Properties for robo-wiki-title

Videos

There are two ways for inserting videos in your documents:

It is recommended to insert videos with built-in tag <robo-wiki-video>, however you may also use standard way for Markdown files.

IPFS / Server

You need to specify format of video

 {% roboWikiVideo {videos:[{src: 'QmYd1Mh2VHVyF3WgvFsN3NFkozXscnCVmEV2YG86UKtK3C', type: 'mp4'}], attrs:['loop', 'controls']} %}{% endroboWikiVideo %} 

About gateways

Gateway for the link is chosen automatically from config file - src/_data/video_config.js. You can add or remove some gateways by changing the file.

Local

 {% roboWikiVideo {videos:[{src: '/videos/add-ext.mp4', type:'mp4'}], attrs:['loop', 'controls']} %}{% endroboWikiVideo %} 

Properties

• If you adding a file with the size of more than 10MB, please, upload it on server, not in repo.

• You may use any properties for HTML5 video tag.

• Acceptable formats - mp4, webm, ogg.

YouTube

You can embed any YouTube video in doc by inserting share link as separate paragraph without any additional quotes or tags, e.g.: https://youtu.be/kQaSwNYHJQ8

However, if you need an autoplay you must use special component:

{% roboWikiYoutube { link:'https://www.youtube.com/watch?v=5s4-S_z4VYE', autoplay: true} %}{% endroboWikiYoutube %}

Properties for robo-wiki-youtube

How to edit sidebar navigation

If you need to edit sidebar navigation of Robonomics Wiki, please, follow these steps:

• Edit file src/_data/sidebar_docs.json.

• Decide where to place your doc

• Use valid JSON for src/_data/sidebar_docs.json and rely on the existing file structure

• You must add new lines to translation file translations/pages/en.json as well, if you are not translated new content before hand, e.g:

{"Launch Robot from Cloud": "Launch Robot from Cloud"}

• IMPORTANT NOTE: if you’re using the same doc in different sections/subsections e.g:

{
	"title": "Upgrade Home Assistant OS",
	"children": [
	{
		"title": "Subscription Activate",
		"url": "/docs/sub-activate",
	}],
	"title": "Upgrade Home Assistant Docker for Unix-like OS",
		"children": [
	{
		"title": "Subscription Activate",
		"url": "/docs/sub-activate",
	}],
}

MAKE SURE TO ADD topic PARAMETER LIKE THIS:

(for navigation to work properly)

{
	"title": "Upgrade Home Assistant OS",
	"children": [
	{
		"title": "Subscription Activate",
		"url": "/docs/sub-activate",
		"topic": "Upgrade Home Assistant OS"
	}],
	"title": "Upgrade Home Assistant Docker for Unix-like OS",
		"children": [
	{
		"title": "Subscription Activate",
		"url": "/docs/sub-activate",
		"topic": "Upgrade Home Assistant Docker for Unix-like OS"
	}],
}

How to add custom navigation for docs

• Edit file src/_data/sidebar_docs.json.

• Find the right doc and add parameters prev and next like this:

	{
		"title": "Overview",
		"url": "/docs/robonomics-smart-home-overview",
		"next": [
			{
				"title": "Add User",
				"url": "/docs/add-user"
			}
		],
		"prev": [
			{
				"title": "Add User",
				"url": "/docs/add-user"
			}
		],
	},

• If you want to remove navigation completely than add withoutNav parameter:

{
	"title": "Overview",
	"url": "/docs/robonomics-smart-home-overview",
	"withoutNav": true
},

• If you want to remove just previous page or next page navigation than add withoutPrev or withoutNext parameter:

{
	"title": "Overview",
	"url": "/docs/robonomics-smart-home-overview",
	"withoutPrev": true
},

or

{
	"title": "Overview",
	"url": "/docs/robonomics-smart-home-overview",
	"withoutNext": true
},

How to translate a document

Important

You must create .env file and add OPENAI_KEY variable with your key

If you wish to translate your md document you need to run the command:

npm run translate-md

Translate easily

To translate all at once, every new lines in pages, new document or changed document you need only one command now

npm run translate-all

Also, make sure you are translating only the changed files that are needed to be translated. For example, you need to change 5 files. Three of them includes text changes and removing some outdated information. And the other two need to update links for some images or just change an external link. In this case, it would be wise to change the first three files and translate them and only then change links in the other two.

Translation happens to all changed files, but it’s not necessary for the updated links, especially if the file large and therefore translation takes some time.

After running the needed command all you have to do is wait and maybe check the files (ai translations have some flaws). To check files run npm run build and see if there are any errors.

Translations troubleshooting

You may run into some troubles with translations.

1. Try to run the command again and see if it worked.

2. Sometimes tags in md files can be written incorrectly, for example:

	[11ty] 1. Having trouble rendering njk template ./src/de/docs/edit-wiki.md (via TemplateContentRenderError)
	[11ty] 2. (./src/de/docs/edit-wiki.md) [Line 168, Column 96]
	[11ty]   unknown block tag: endroboWiki (via Template render error)



	{% roboWikiPicture {src:"docs/datalog/extrinsics.jpg", alt:"extrinsics"} %}{% endroboWikiPicture {% endroboWikiPicture %}



	{% roboWikiPicture {src:"docs/datalog/extrinsics.jpg", alt:"extrinsics"} %}endroboWikiPicture %}

Then, you just need to fix the tag.