Eclipse Che documentation
Che docs use Jekyll to convert
.adoc (AsciiDoc) files into HTML pages. Docs are published at https://www.eclipse.org/che/docs. Updates are synced with a release cycle.
Build and preview
There is a
run.sh script in the root of the repo that runs a Docker image, mounts sources, and starts Jekyll. When running locally, docs are available at
localhost:4000. Jekyll watches for changes in
.adoc files and re-generates resources, so you can preview changes live.
To build without using Docker, install required Jekyll dependencies:
# yum install maven ruby ruby-devel @development-tools
Then, instead of the
run.sh script, run Maven directly:
$ mvn clean install -Pnative
Adding a new page
In order to add a new page, create an
.adoc file in
<MAJOR-VERSION> for either
7, depending for which version of Che your content is intended).
If there is no sub-directory that fits a new page, create one. Look at headers in existing pages to make sure the generated HTML page has the expected name, title, and keywords. For example:
--- title: "Installing single-user Che on Docker" keywords: docker, installation tags: [installation, docker] sidebar: che_6_docs permalink: docker-single-user.html folder: setup ---
Try to use short names and titles for pages. Use dashes (
-) in page names (
permalink in page header).
The search script uses page titles, summary, and keywords to search for relevant results. Make sure your keywords are relevant for the page you add.
To add a tag, look at available tags in
src/main/pages/che-<MAJOR-VERSION>/tags folder. Tags should be also registered in
src/main/_data/tags.yml - so both a tag in
tags.yml and a respective tag page should be created.
Formatting and AsciiDoc syntax
See AsciiDoc Writer's Guide for syntax and general help with AsciiDoc.
To post a link to an internal page, use the following syntax:
This is a link:file_name.html[link to an internal page]
Do not use
.adoc in the file name. Also, this file should be referenced in at least one sidebar-definition file in the
Links to anchors in internal pages:
link:file_name.html#tag[link to an anchor on an internal page]
Links to external pages:
This is a link:https://github.com[link to an external site]
Images are located in the
src/main/che/docs/images/ directory. To publish an image, use the following syntax:
Do not add images into the root of the
images/ directory - either choose an existing sub-directory or create one if none of them fits the new image.
Images are sized automatically. You can provide a URL to a full-size image, as well as a caption and alt text:
.Click to view a larger image [link=che/docs/images/devel/js_flow.png image::devel/js_flow.png[Alt text]
Do not post too many images unless it is absolutely necessary. Animated
.gif images are preferred, especially when explaining how to use complex UI features.
To prevent special characters from being interpreted as formatting mark-up, use pass-through macros. For example, to escape underscores, asterisks, or backticks, use:
How to get support
Public Chat: Join the public eclipse-che Mattermost channel to talk to the community and contributors
How to contribute
We love pull requests and appreciate contributions that make docs more helpful for users. See the Contribution guide.