Versions Compared

Old Version 1

changes.mady.by.user Benjamin Reed

Saved on

compared with

New Version Current

changes.mady.by.user Patrick Hunt

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The ZooKeeper website is build using CMS and uses the ZooKeeper SVN repository as the content respository. Specifically, the site subdirectory under the root of the ZooKeeper SVN repository has the ZooKeeper website. We use textile markup for our pages and doc. Textile is a reasonably powerful markup language that also matches the markup used by confluence, our wiki system.

File layout

There are two key subdirectories in the site directory: content and templates. The content subdirectory has the textile files that will be transformed to HTML files by CMS. The templates subdirectory has the template files for the pages. The sidenav.textile template file contains the side navigation bar and is the template file most often changed, usually to point to new releases.

CMS will automatically build and stage a new website when changes are committed to the the site directory and its children. The staged site is made public using the CMS web interface.

The BookKeeper website and ZooKeeper doc is loaded pulled in using svn:externals, which is kind of like a symlink for SVN. These are added using svn propedit svn:externals . in the parent directory.

Unfortunately, changes to these linked directories are not detected by CMS, so to cause a new build to be generated for changes to linked directories we need to change something in the main directory. The file build_trigger exists for this reason. The file is not used for anything out. Just make an arbitrary change to the file and check it in to kick off a build which will pickup any changes from the linked directory.

CMS

To build the website on your local machine, you need to checkout the CMS build system from https://svn.apache.org/repos/infra/websites/cmsImage Removed. You can then run the build/build_site.pl to build the website.

...

built using Markdown sources. The production website is updated using gitpubsub via the zookeeper.git/asf-site branch. Basic workflow is: modify the site source on the "website" branch and commit it once you are happy with the results, then update the "asf-site" branch with the generated content. Once asf-site is pushed the updates will be reflected on the ZooKeeper production website.

The content source to generate the ZooKeeper website can be found here: https://gitbox.apache.org/repos/asf?p=zookeeper.git;a=shortlog;h=refs/heads/website

The live website is whatever is committed to asf-site, here: https://gitbox.apache.org/repos/asf?p=zookeeper.git;a=shortlog;h=refs/heads/asf-site . Any changed committed to this branch are immediately replicated to the live production website at http://zookeeper.apache.org/

Information on running the website generation process can be found in the README.md file on the website branch, similar for managing the asf-site.

Prerequisites

The ZooKeeper website build uses Apache Maven and a maven plugin generating HTML from MarkDown sources.

Besides maven you don't have to install anything else.

Steps to update the site:

1. git clone -b website https://gitbox.apache.org/repos/asf/zookeeper.git

2. update the appropriate pages, typically a markdown file e.g. credits.md, etc...

3. mvn clean install

4. cp -RP _released_docs target/html/doc These are the static release docs, not generated in this process.

At this point verify that the generated files render properly (open target/html/index.html in a browser). If you are happy with the results move on to the next step, otherwise go to step 2 above.

5. git status should show modified files for the markdown that you changed

6. git add <the changed files>

7. git commit -m "<appropriate commit message>"

8. git push origin website

The source for the site is committed, now we need to push the generated files to the live site.

9. git checkout asf-site

10. rm -fr content

11. mv target/html content

12. git add content

Verify that content/index.html and other generated files are proper, e.g. open them in a browser

13. git status should show modified files for the markdown that you changed

14. git commit -m "<appropriate commit message>"

15. git push origin asf-site