hanhuece / che-docs Goto Github PK

Che docs use Jekyll to convert .md files into html page. Docs are published at https://www.eclipse.org/che/docs. Updates are synced with a release cycle.

There's 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 .md files and re-generates resources, so you can preview changes live.

In order to add a new page, create .md file in src/main/pages/${subdir}. If there's no sub-directory that fits a new page, create one. Take a look at headers in pages to make sure the generated html page has expected name, title and keywords.

---
title: "Single-User&#58 Install on Docker"
keywords: docker, installation
tags: [installation, docker]
sidebar: user_sidebar
permalink: docker.html
folder: setup
---
{% include links.html %}

{% include links.html %} is mandatory to enable links to other pages.

Try to use short names and titles for pages. Use _ or - in page names (permalink in page header).

Search script uses page titles, summary and keywords to search for relevant results. Make sure your keywords are relevant for the page you add.

If you need to add a tag, take a look at available tags in src/main/pages/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.

To post a link to an internal page, use the following syntax:

This is a [link][file_name]

Do not use .md or .html. Also, this file should be referenced in at least one sidebar src/main/_data/sidebars

Links to anchors in internal pages:

This is a [link](file_name.html#tag)

Links to external pages:

This is a [link](https://github.com)

Images are located in src/main/images

To publish an image, use the following syntax

{% include image.html file="dir/img.png" %}

Do not drop images into the root of images directory - either choose an existing sub-dir or create one if none of them fit an image.

Images are sized automatically. You can provide a URL to a full size image, as well as a caption:

{% include image.html file="devel/js_flow.png" url="images/devel/js_flow.png" caption="Click to view a larger image" %}

Please, 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.

• GitHub issue: open an issue in this repository
• Public Chat: Join the public eclipse-che Mattermost channel to discuss with community and contributors

We love pull requests and appreciate contributions that make docs more helpful for users. See: Contribution guide.