Repository: incubator-apex-site Updated Branches: refs/heads/master fbcb03602 -> 9da328778
updated README with better info Project: http://git-wip-us.apache.org/repos/asf/incubator-apex-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-apex-site/commit/9da32877 Tree: http://git-wip-us.apache.org/repos/asf/incubator-apex-site/tree/9da32877 Diff: http://git-wip-us.apache.org/repos/asf/incubator-apex-site/diff/9da32877 Branch: refs/heads/master Commit: 9da328778c2bc5e8baee05838cb7c1ff927cfe1a Parents: fbcb036 Author: Andy Perlitch <[email protected]> Authored: Fri Sep 18 09:57:02 2015 -0700 Committer: Andy Perlitch <[email protected]> Committed: Fri Sep 18 09:57:02 2015 -0700 ---------------------------------------------------------------------- README.md | 77 +++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 52 insertions(+), 25 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-apex-site/blob/9da32877/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index b1e5c30..00721b8 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,47 @@ Apache Apex Incubator Website ============================= -This is the source code for the Apache Apex Incubator website, hosted at [apex.incubator.apache.org](http://apex.incubator.apache.org/). +This is the source code for the Apache Apex Incubator website, hosted at [apex.incubator.apache.org](http://apex.incubator.apache.org/). The following tools are used to build the html pages: + +- [nodejs + npm](https://nodejs.org/en/) +- [gulp - nodejs automation tool](http://gulpjs.com/) +- [handlebars.js - templating](http://handlebarsjs.com/) +- [LESS - css pre-processor](http://lesscss.org/) +- [Marked - Markdown parser/compiler](https://github.com/chjj/marked) +- [Bootstrap - HTML/CSS/JS framework](http://getbootstrap.com/) +- [jQuery](https://jquery.com/) How it works ------------ -The master branch of this repo contains the files that are used to generate the HTML that ultimately gets pushed to the incubator site. +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 *Building* section below. +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](http://www.apache.org/dev/gitpubsub.html) mechanism on the apache.org server, files are taken from the `asf-branch` and pushed to the live server. -Partials --------- -All pages on the site share the same header and footer. These are stored in the `src/partials` folder. - Pages ----- -Pages are stored in the `src/pages` folder. Each page should look something like this: +Pages are stored in the `src/pages` folder. Each page uses the [handlebars templating engine](http://handlebarsjs.com/), and should look something like this: ```HTML -{{> header}} +{{> header}} <!-- includes the header.handlebars partial --> <h1>Hello World</h1> <p>I am a page.</p> -{{> footer}} +{{> footer}} <!-- includes the footer.handlebars partial --> ``` -## Markdown files +Partials +-------- +All pages on the site share the same header and footer. These are stored in the `src/partials` folder. You can put other partials in here and they will be made available to all templates (the `.handlebars` extension is dropped). -If you have a block of content that you would like to render as markdown, you can do so by creating a `.md` file in the `src/md/` folder. -These will be picked up, rendered has html, and passed into your page templates as partials. +Markdown files +-------------- +If you have a block of content that you would like to render from a markdown file, you can do so by creating a `.md` file in the `src/md/` folder. +These `.md` files will be picked up, rendered has html, and exposed to page templates as partials. Assuming you have a file called `src/md/example_markdown.md`, you could have this in a page template: ```HTML @@ -46,17 +54,36 @@ Assuming you have a file called `src/md/example_markdown.md`, you could have thi {{> footer}} ``` -Building (requires node+npm) ----------------------------- -Run `build.sh` from the directory. This will: - -- ensure the necessary npm and bower dependencies are installed -- checks out and updates the `asf-site` branch with a new commit of the build from the current branch - -You must manually push to the `asf-site` remote branch. +Contributing +------------ +If you would like to make a change to the site: + +1. Fork the [github mirror](https://github.com/apache/incubator-apex-site) +2. Create a new branch from `master` +3. Add commit(s) to your branch +4. Test your changes locally (see Development section below) +5. Open a pull request on the github mirror +6. A committer will merge your changes if all is good + +If you are a committer, do the following: + +1. Update the master branch with your (or a Pull Request's) change. +2. Push updated master to the asf remote master (https://git-wip-us.apache.org/repos/asf/incubator-apex-site.git) +2. Run `build.sh` from the master branch directory (requires nodejs and npm). This will: + - ensure the necessary npm and bower dependencies are installed + - checks out and updates the `asf-site` branch with a new commit of the build from the current branch +3. At this point, you should be on the `asf-site` branch. Simply push this branch to the asf remote and the site will automatically be updated within seconds. + +Development +----------- +To set up the proper dev environment for this site, run the following: + +```bash +npm install +./node_modules/.bin/bower install +./node_modules/.bin/gulp watch +``` -Developing ----------- -When making changes to src files, you can run `grunt watch`, which will constantly build the project in the `/content` folder, -so you don't have to manually run `grunt` after every change \ No newline at end of file +The `gulp watch` command will start a process that watches for changes to source files and updates the `/content` folder accordingly. +Simply open `/content/index.html` in your browser and refresh the page when you make changes. \ No newline at end of file
