It's a straightforward process to create Liferay documentation. The goal is to create docs the developers want to read and to keep the style consistent and clear regardless of author. For these reasons, we've outlined the process and procedure below.
Liferay Documentation is written in Markdown. The file extension should
be .markdown. Your text editor of choice can be used as long as you use
the following conventions:
- All files are hard-wrapped at 80 columns
- Use spaces instead of tabs because of the way Markdown processes indents
- Every sentence, including those at the ends of paragraphs, should have a trailing space
- Leave one blank space between headings and the paragraphs that follow
- Links should start on their own line and not wrap
Markdown files are created in a folder structure that is parsed by our Knowledge Base importer. The idea is to create a reading environment like this:
There are three areas to notice: the menu on the left, the article on the right,
and the list of articles at the bottom right. When a user clicks on a topic,
that topic opens. There could be one or several tutorials on that topic. The
first of these is the intro file. This is marked in the file system by
appending -intro to the file name (for example,
service-builder-intro.markdown).
Nesting is done by folders, and every folder must have an -intro file. In the example above, therefore, you have this folder structure:
When a user, therefore, clicks on Tooling, LDN displays
00-intro.markdown on the right and expands the navigation on the left.
When a user clicks on Liferay IDE, LDN displays the
00-liferay-ide-intro.markdown file and the navigation is further expanded.
Notice that in the file system, the folders are numbered. This is how the topics are ordered on LDN. The topic titles, however, are taken from the heading in the -intro file, so it's important to put the proper headings in those files.
All Liferay Developer Network articles reside in
liferay-docs repository folders that are laid out in a similar manner to
LDN's pages and articles. Each repository folder under discover,
develop, and distribute represents a section of
LDN's articles. For example, the discover/portal folder
contains Markdown files and images that are the source for LDN's
User & Admin → User Guide
articles.
The following tables show the folder locations for articles published to LDN's User & Admin, Developer, and Marketplace sections.
Source Folders for Liferay Developer Network Articles:
 |
|---|
| liferay-docs/discover/ |
• portal/ → Portal |
• social-office/ → Social Office |
• deployment/ → Deployment |
• reference/ → Reference |
• new-articles/ (You can submit new articles here for LDN's User & Admin section) |
 |
|---|
| liferay-docs/develop/ |
• learning-paths/ → Learning Paths |
• tutorials/ → Tutorials |
• reference/ → Reference |
• new-articles/ (You can submit new articles here for LDN's Developer section) |
 |
|---|
| liferay-docs/distribute/ |
• distribute/new-articles/ (You can submit new articles here for LDN's Marketplace section) |
First, you need a copy of the repository on your own machine, and to do that, you must clone the project. For information on how to work with Git projects, see How do I use Git and GitHub?.
To add an article to LDN's Develop
section (as an example), create your article and its images in the
liferay-docs/develop/new-articles folder. Commit your added files and send a
pull request to default
user liferay. For more information on where to place new articles and for
guidelines on writing them, see
How do I write and submit my own article?.
To modify an article, you can edit it locally in its repository location, in
a branch created for that purpose. After you've made your changes, commit them
and submit a pull request to the
default user liferay.
To preview an article, invoke one of the convert.[bat|sh] scripts
on your Markdown file. The scripts are in the bin folder. See
How do I convert my local Markdown to HTML using the provided convert scripts?
for details on using the script.
As you write documentation, you'll want to be aware of our standards and customizations. Click here