Vert.x 3.x web-site

The Vert.x 3.0 web-site repository

This repository is containing the Vert.x Web Site source. The web site is available on: http://vertx.io.

Building

Building the production version

mvn clean site

This will assemble and transform the various parts of the site and place it in target/site.

Then open target/site/index.html. Notice that all links targets http://vertx.io.

Building a dev version with gulp

If you have gulp install and want to work on the web site with "hot redeploy" of your change:

mvn clean site; gulp watch

Then open http://localhost:4000.

The documentation pages will not be rebuilt continuously. If you change the header or footer templates and want to update the documentation pages, you need to stop the watch mode with Ctrl+C and start it again with gulp watch.

Building a dev version with docker

(No hot-redeploy)

If you don't have gulp, you can build a version of the web site running in a docker container:

To build:

• Linux: mvn site -Pdocker -Dhost=localhost:4000
• Mac: mvn site -Pdocker -Dhost=192.168.99.100:4000

To run:

docker run -p 4000:80 vert-x3/vertx-web-site

Open your browser to:

• Linux: http://localhost:4000
• Mac: http://192.168.99.100:4000

Checking for broken links

You can run a gulp task that will build the website and then check for broken links.

gulp check-links

Make sure you have built the website with mvn site first if you haven't done so already.

A word on URLs

All URLs and links in the website should be absolute. You can use the template string {{ site_url }} to make a relative URL absolute. For example, if you want to add a link to the documentation pages, use the following HTML tag: <a href="{{ site_url }}docs">...</a>. The global site_url variable already contains a trailing slash. You can configure it in the gulpfile.js file.

Heads up: keeping all URLs absolute allows us to quickly move the web-site to another path on the web server by just changing the global site_url variable.

In order to obtain nice URLs, all pages should be put in their own directory and called index.html. For example, the entry page of the blog is under blog/index.html. Therefore it can be reached under http://vertx.io/blog. If you link to such a page always use the nice URL (without index.html).

The blog

Read BLOG.md

Publishing

Run mvn site-deploy to publish the site to your GitHub account. Configure the correct URL to your repository in the pom.xml file.

Update contributors

The file src/main/community/contributors.js contains a list of developers working full time on Vert.x and other contributors. Change this file manually to add new people.

To automatically generate a list of contributors who are not already defined in contributors.js run gulp update-contributors. The script retrieves a list of people who contributed to Vert.x projects (i.e. projects from the vert-x3 organisation on GitHub) and saves it to src/generated/community/contributors-gen.js. Never edit this file directly. It will always be overwritten by the update-contributors gulp task.

The task creates a lot of requests against the GitHub API. GitHub limits the number of requests for anonymous clients. In order to increase the limit you need a client ID and secret. Go to https://github.com/settings/developers and register a new application. Then edit github.json and enter your client ID and secret.

Do not commit your client ID and secret to the repository! In order to avoid that you accidentally publish your credentials, run git update-index --assume-unchanged github.json. Git will then ignore all local changes to the github.json file.