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

PropertyTypeRequiredDefaultDescription
copyBooleanfalsefalseadd a copy button for your code
additionalLineStringfalse‘’additional line for you code that will be displayed above
additional line
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

PropertyTypeRequiredDefaultDescription
columnsNumberfalse4you can choose column number:
- from 1 to 5
alignStringfalsealign items on the block axis:
- options: start, center, end
justifyStringfalsealign items on the inline axis:
- options: start, center, end
textAlignStringfalseleftalign text inside grid:
- options: left, center, right
need
Raspberry Pi 4 (at least 2 GB RAM)
need
SD card 16Gb

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:

PropertyTypeRequiredDefaultDescription
srcStringtruepath to the image:
- if you uploaded your image directly to the /src/assets/images/docs/ use: url-of-your-doc
- if you uploaded image in one of the folders than use: folder-name/url-of-your-doc
linkStringfalsealign items on the block axis:
- options: start, center, end
captionStringfalsealign items on the inline axis:
- options: start, center, end
altStringtruepictureprovides alternative information for an image if a user for some reason cannot view it
zoomBooleanfalsezoom image
loadingStringfalselazythere are two options: lazy and eager

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.

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


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

Properties for robo-wiki-note

PropertyTypeRequiredDefaultDescription
typeStringfalse- there are three types in total: note, warning, okay
titleStringfalseadds title to your 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)

PropertyTypeRequiredDefaultDescription
tabsArraytrue- Array with titles for each tab
modeStringfalsehorizontalyou can choose tabs mode:
- horizontal
- vertical

Properties for robo-wiki-tab (item)

PropertyTypeRequiredDefaultDescription
borderBooleanfalsefalse- add border to the content wrapper
  • Linux
  • OSX
ip a
ifconfig 
  • Linux
  • OSX
ip a
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

PropertyTypeRequiredDefaultDescription
typeNumber (from 2 to 6)truechoose heading level
anchorStringfalsevalue for the anchor

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.

PropertyTypeRequiredDefaultDescription
videosArraytrueArray of objects [{src: path to video, type: type of video}]

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

PropertyTypeRequiredDefaultDescription
linkStringtruelink to youtube video
autoplayBooleanfalsefalseautoplays youtube video
loopBooleanfalsefalseloops youtube video

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

  • 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

After running the command all you have to do is wait and maybe check the files (ai translations have some flaws).

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.

Couldn't complete

Thanks,
we'll keep in touch!

It was hard

Thanks,
we'll keep in touch!

It was ok

Thanks,
we'll keep in touch!

It was easy

Thanks,
we'll keep in touch!
Main contributors: @positivecrash
Make a contribution

Robonomics wiki is open source. See something that's wrong or unclear? Submit a pull request.

Latest commit on 01.10.2024 by Julia
? Ask your question