Apache Edgent website
Location
http://edgent.incubator.apache.org/
How it works
This procedure was borrowed in part from the Apache Apex site except we use Jekyll.
The master
branch of this repo contains the source files that are used to generate the HTML that ultimately gets pushed to the incubator site. The asf-site
branch is where the actual generated files are stored. Note that this branch must contain exactly one folder called content
, and so has been checked out as an orphan branch with its own commit history apart from the master
branch. See the Contributing section below.
Through a gitpubsub mechanism on the apache.org server, files are taken from the asf-site
branch and pushed to the live server.
Contributing
If you would like to make a change to the site:
- Fork the GitHub mirror
- Create a new branch from
master
- Add commit(s) to your branch
- Test your changes locally (see the Developing section)
- Open a pull request in the GitHub mirror
- A committer will merge your changes if all is good
If you are a committer, do the following:
- Update the master branch with your (or a Pull Request's) change
- Push updated master to the ASF remote master
- Run
build.sh
from the master branch directory (requires Jekyll). This checks out and updates theasf-site
branch with a new commit of the build from the current branch. - At this point, you should be on the
asf-site
branch. Simply push this branch to the asf remote withgit push origin asf-site
and the site will automatically be updated within seconds.
Note: If you want to try out the website locally on the asf-site branch before you push, you can do so with jekyll serve -d content --skip-initial-build
and point your browser to http://localhost:4000
.
Style Guide
The website utilizes Markdown as the basis for website content. This cheatsheet may prove useful.
In order to ensure a consistent user experience, these guidelines should be followed:
- For all headers, use sentence-style capitalization
- Capitalize the first word of the title/header or subtitle/subheader
- Capitalize any proper nouns and certain other types of words (e.g., programming terms)
- Use lowercase letters for everything else
- Page headers should start at Level 2 using
##
in order to have them be automatically added to the Table of Contents - Do not skip header levels. For instance, do not jump from
##
to####
. - Use section headings as a way to separate large blocks of content and as reference markers in the Table of Contents
- Code references (e.g., to a Java class) should be placed in inline code blocks using a single backtick
`
- For code blocks, use three backticks
```
, and if applicable, specify the language for syntax highlighting - Avoid using raw HTML tags. Use the equivalent Markdown syntax.
- Whitespaces
- Use one whitespace between sentences.
- Use one blank line between paragraphs for the best readability
- Do not use leading whitespace, except for special cases, such as indenting within list items
- Do not use trailing whitespace, except for the case where a line break is needed. In that case, end a line with two spaces.
- Use correct spelling and grammar, especially for references to other projects. For example, use GitHub, not Github.
Developing
- Make your changes under the
site
directory:cd site
jekyll serve
- Point your browser to
http://localhost:4000