Spring's project pages are based on [Jekyll](https://jekyllrb.com) and [GitHub Pages](https://pages.github.com/). This means that each project's website is stored within the project repo, in a special branch called "gh-pages". In order to keep everything looking similar across the many individual Spring projects, common elements of the Jekyll site layout, css, etc are stored in [a shared gh-pages repository](https://github.com/spring-projects/gh-pages). If you're seeing this README in the gh-pages branch of an actual Spring project, that's because this file, along with all the other common files get merged periodically into each project.
This approach may sound a little funky (and it is), but it's way better than the misery of Git submodules. In fact, it's actually pretty easy. If you're just getting started, then follow the directions immediately below. If you're needing a refresher on how to keep things up to date, then head to the section at the bottom on "keeping up to date".
> ***Note:*** Github changed their rendering (a lot) in April 2016. If you are seeing pages build failures since that time, then you probably need to merge some changes from this upstream. Follow the instructions below, and for testing locally use rubiy 2.x and don't forget to `bundle exec ...` everything.
You'll need to tweak a few settings in `_config.yml`, sitting in the root directory. Edit this file and follow the instructions within. It should be self explanatory; you'll see that there are lots of instances of "spring-framework" as a project name. You should replace these with your own project's information as appropriate.
## Create the project home page
### What kind of project are you?
At this point, you just need to give your project a home page. There are pre-fab samples included in the `_sample-pages` directory:
$ ls -1 _sample-pages
documentation.md
project_group.html
project.html
vaniall.md
At this point you need to make a decision: is your project a "grouping project", like Spring Data, acting as a parent for one or more child projects? If so, you should choose `project_group.html` in the following step. Otherwise, if you're dealing with an individual, concrete Spring project, e.g. Spring Data JPA, or Spring Security OAuth, you should choose `project.html`. The `documentation.md` can be used when you want to expose README.md files on your site.
### Copy the sample page to `index.html`
Based on your choice above, copy the correct sample page to `index.html`, e.g.:
Open up `index.html` in your favorite text editor. Within, you'll find "YAML front matter" at the top of the file, i.e. everything between the triple dashes that look like `---`. This section contains some basic metadata, and—if you've copied the `project.html` sample—also contains a custom section of information for your project "badges". These are icons that will render in the sidebar of your project page.
Edit the URLs and other values in the YAML front matter as appropriate. This should be self-explanatory.
> **Tip**: If a particular "badge" (e.g. Sonar) does not apply to your project, just delete that entry from the YAML.
### Understand the use of "captures" and "includes"
Next, you'll see a series of `{% capture variable_name %}` blocks that look like this:
{% capture billboard_description %}
...
{% endcapture %}
At the end of the file you'll see a `{% include %}` directive that looks like this:
{% include project_page.html %}
That `include` directive is the most important part. It brings in `project_page.html`, which will actually be responsible for rendering the page content.
The net effect is that you have one simple place to edit actual page content, and the actual rendering and placement of that content is handled for you by the include.
Ideally, you shouldn't have to touch any other files besides `_config.yml` and `index.html`, but of course if you need to you always can.
### Replace the filler text with copy specific to your project
Of course the next step is simply to change the prose within each `{% capture %}` block to read as you want it to. It's just Markdown, so do as you please with that in mind. Note that you'll want to move on to the next step to view the site locally before you get too far into the editing process; this will allow you view your changes live as you make them.
## View the site locally
Assuming you're already within your project's clone directory, and you've already checked out the `gh-pages` branch, follow these simple directions to view your site locally:
> **Note:** Jekyll 3.0.4 is a known good version, and it is specifically referred to in `Gemfile.lock` so you have to use `bundle` (not `gem install ...`) to install it:
> **Important:** Because the `baseurl` is set explicitly within your project's `_config.yml` file, you'll need to fully-qualify the URL to view your project. For example, if your project is named "spring-xyz", your URL when running Jekyll locally will be <http://localhost:4000/spring-xyz/>. Don't forget the trailing slash! You'll get a 404 without it.
## Commit your changes
Once you're satisified with your edits, commit your changes and push the `gh-pages` pages up to your project's `origin` remote.
