Excerpt |
---|
Explains how to modify the Trafodion web site, which is written in markdown and built using Maven. |
...
Table of Contents | ||||
---|---|---|---|---|
|
...
You develop and test all changes in the Trafodion source tree. Once checked in and built, the content of docs/target
plus the documentation (refer to Modify Documentation above) are copied to https://git-wip-us.apache.org/repos/asf/trafodion-site.git. The changes are then pushed out by Apache gitpubsub, thereby populating http://trafodion.apache.org.
Making Changes
The following information helps you understand how to make changes to the web-site content.
Technology
The Trafodion website uses the following technologies:
- Framework: Apache Maven Site
- Skin: Reflow Maven Skin
- Theme: Bootswatch Cerulean
- Markdown: markdown (markdown was chosen since it supports in-line HTML, which provides better table control than APT. Asciidoc does not work well with the Reflow Maven Skin; we tested.)
Info |
---|
Markdown supports basic tables only; that is, you’ll need to use |
Code Organization
The code is located in the docs
directory. The code organization follows the Maven standard.
docs/src/site/site.xml
is configured per the Reflow Maven Skin documentation. Pages and menus are defined and configured in this file. By default, all pages use an automated table of contents; override as needed.docs/src/site/markdown
contains the files that generate the different HTML files.docs/target
contains the generated HTML files after you run a build.
Managing Pages
You add/rename/delete pages in docs/src/site/markdown
. You make corresponding changes in docs/src/site.xml
adding/renaming/deleting pages from menus and defining page configuration; for example: removal of the table of contents bar and the special page formatting provided by the Reflow skin. Refer to the Maven Documentation for more information.
Providing Content
When possible, ensure that you write in active voice and to the point.
Special functions such as buttons etc. can be access by clicking Preview in the theme preview. There’s a <>
feature on each function, which allows you to copy the special <div>
you need to insert the selected object.
Development Environment
Typically, you’ll use Eclipse to develop and build the website pages. After obtaining the Trafodion source and starting Eclipse, you'll find the Docs project under File->Import->Import Existing Projects. Select the Maven drop down and then Existing Maven Projects. Browse to the top of your Trafodion source tree and select OK. Then select all of the projects that you want to import and add to the trafodion working set. Then click Finish.
To set up the build environment, go to the Package Explorer in Eclipse and select the Trafodion package. Select Run from the menu and name and create a configuration using the configuration goal clean site
. The pom.xml
file in the top-level directory drives the build steps for the web site.
Then run the newly-created configuration to build the website
Testing Changes
The website files are located in docs/target
. Open index.html
from your browser and test your changes. For example, you want to validate the page layout, page navigation, links, and review the overall content on the pages you modified or added/deleted.
Tables
markdown supports a simple format for tables. You can use markdown-style writing in such tables.
Code Block | ||
---|---|---|
| ||
Table Header | Table Header ---------------|--------------- Text | Text Text | Text |
However, no special formatting can be done; for example, creating a bulleted list in a cell. If you need tables with such formatting, then you will need to define the table in raw HTML format. No markdown-style writing is supported for HTML tables; use pure HTML tagging instead.
Call-Out Boxes
You can create a simple callout box using an HTML table.
Example
Code Block | ||
---|---|---|
| ||
<table><tr><td><strong>NOTE</strong><br />Whatever you want to say here.</td></tr></table> |
Generates
Info | ||||
---|---|---|---|---|
| ||||
Whatever you want to say here. |
Publishing
Info |
---|
Publication is done when a committer is ready to update the external web site. You do not perform these steps as part of checking in changes. Publishing steps are documented in Merge Changes. |
Logo
The source files for the different Trafodion logos are implemented using Adobe Illustrator. The file extension is .ai. Use Adobe Illustrator or an alternative graphics package that can import .ai files. The source files are attached to this page.