3.5 KiB
| layout | title |
|---|---|
| editable | Contribution Guidelines |
This document explains how to contribute changes to the IntelliJ SDK Platform Documentation project.
Licensing
Project source code terms of use, reproduction, and redistribution is defined by Apache 2.0 license
Contributing Changes
Users with Write Access
To contribute your changes clone the project, implement your changes, and push them to the repository.
Users with Read-Only Access
To contribute you changes use a pull request. Creating a pull request article on GitHub explains how to do it.
Setting Up Environment
To build and run the project locally you need to set up its development environment, Refer to the README section of this project.
Project Structure
The project contain the following major types of content:
- Articles An article describes some part of the API and general rule of using it in a free form.
- Step-by-step tutorials
- Code samples
Markup
Documents are written in Markdown markup template language. Processing of Markdown source code and conversion into HTML is made by Kramdown library.
Creating an Article
To post an article, create a Markdown document inside of the project directory structure. Jekyll engine will process all the Markdown files inside the project and create corresponding static HTML pages with same relative paths for them. To process a Markdown file you need to refer to it's HTML counterpart in _SUMMARY.md
Table of Contents and _SUMMARY.md
File _SUMMARY.md located in the root directory defines project's hierarchical structure displayed on the left side of the page in a tree form. Place the name of an article and a link relatively to the site root to the corresponding HTML document to _SUMMARY.md to list the article in TOC. Headers without links to corresponding files won't be visible. Files not included in the listing wont be processed.
Formatting Rules
Text
To make the source code easy to read, start every new sentence from a new line. Avoid semicolons, long sentences, and complicated formulations.
Links
Place every link separately on a new line
Please refer to the
[following article](http://link.address)
to get more information
Project Structure
All the documentation is logically divided into three major parts:
- Basics Contains information required to get familiar with the plugin development environment and the API
- Architecture Reference Guide More in-depth API description
- Tutorials Series of steps and code samples that show how parts of the API can be use in practice
Your article should be placed in one of these three categories dependently on the type of the content.
Child Documents
To place child documents, create a subdirectory named like a parent article and place all the child documents in it.
Images
To place images for an article, in the article's directory root create a subfolder named <article_name>/img. Please downscale screenshots made at high resolution.