|
| 1 | +# Introduction |
| 2 | + |
| 3 | +Spring's project pages are based on [Jekyll](http://jekyllrb.com) and [GitHub Pages](http://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](http://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. |
| 4 | + |
| 5 | +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". |
| 6 | + |
| 7 | + |
| 8 | +# How to start a new `gh-pages` project page |
| 9 | + |
| 10 | +From within your Spring project's git checkout directory: |
| 11 | + |
| 12 | +### Create and checkout the gh-pages branch |
| 13 | + |
| 14 | + git checkout --orphan gh-pages |
| 15 | + |
| 16 | +### Remove all files |
| 17 | + |
| 18 | + git rm -rf * |
| 19 | + git rm -rf '.*' |
| 20 | + |
| 21 | +### Add the gh-pages-upstream remote |
| 22 | + |
| 23 | + git remote add gh-pages-upstream https://github.com/spring-projects/gh-pages.git |
| 24 | + |
| 25 | +### Pull in the common site infrastructure |
| 26 | + |
| 27 | + git pull gh-pages-upstream gh-pages |
| 28 | + |
| 29 | + |
| 30 | +## Edit `_config.yml` |
| 31 | + |
| 32 | +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. |
| 33 | + |
| 34 | + |
| 35 | +## Create the project home page |
| 36 | + |
| 37 | +### What kind of project are you? |
| 38 | + |
| 39 | +At this point, you just need to give your project a home page. There are pre-fab samples included in the `_sample-pages` directory: |
| 40 | + |
| 41 | + $ ls -1 _sample-pages |
| 42 | + documentation.md |
| 43 | + project_group.html |
| 44 | + project.html |
| 45 | + vaniall.md |
| 46 | + |
| 47 | +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. |
| 48 | + |
| 49 | +### Copy the sample page to `index.html` |
| 50 | + |
| 51 | +Based on your choice above, copy the correct sample page to `index.html`, e.g.: |
| 52 | + |
| 53 | + $ cp sample-pages/project.html index.html |
| 54 | + |
| 55 | +or |
| 56 | + |
| 57 | + $ cp sample-pages/project_group.html index.html |
| 58 | + |
| 59 | + |
| 60 | +## Edit the content of your home page |
| 61 | + |
| 62 | +### Edit the YAML front matter |
| 63 | + |
| 64 | +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. |
| 65 | + |
| 66 | +Edit the URLs and other values in the YAML front matter as appropriate. This should be self-explanatory. |
| 67 | + |
| 68 | +> **Tip**: If a particular "badge" (e.g. Sonar) does not apply to your project, just delete that entry from the YAML. |
| 69 | +
|
| 70 | +### Understand the use of "captures" and "includes" |
| 71 | + |
| 72 | +Next, you'll see a series of `{% capture variable_name %}` blocks that look like this: |
| 73 | + |
| 74 | + {% capture billboard_description %} |
| 75 | + ... |
| 76 | + {% endcapture %} |
| 77 | + |
| 78 | +At the end of the file you'll see a `{% include %}` directive that looks like this: |
| 79 | + |
| 80 | + {% include project_page.html %} |
| 81 | + |
| 82 | +That `include` directive is the most important part. It brings in `project_page.html`, which will actually be responsible for rendering the page content. |
| 83 | + |
| 84 | +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. |
| 85 | + |
| 86 | +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. |
| 87 | + |
| 88 | +### Replace the filler text with copy specific to your project |
| 89 | + |
| 90 | +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. |
| 91 | + |
| 92 | + |
| 93 | +## View the site locally |
| 94 | + |
| 95 | +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: |
| 96 | + |
| 97 | +### Install jekyll if you have not already |
| 98 | + |
| 99 | +> **Note:** Jekyll 1.1.2 is a known good version. |
| 100 | +
|
| 101 | + gem install jekyll |
| 102 | + |
| 103 | +### Run jekyll |
| 104 | + |
| 105 | +Use the `--watch` flag to pick up changes to files as you make them, allowing you a nice edit-and-refresh workflow. |
| 106 | + |
| 107 | + jekyll serve --watch |
| 108 | + |
| 109 | +> **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. |
| 110 | +
|
| 111 | + |
| 112 | +## Commit your changes |
| 113 | + |
| 114 | +Once you're satisified with your edits, commit your changes and push the `gh-pages` pages up to your project's `origin` remote. |
| 115 | + |
| 116 | + git commit -m "Initialize project page" |
| 117 | + git push --set-upstream origin gh-pages |
| 118 | + git push |
| 119 | + |
| 120 | + |
| 121 | +## View your site live on the web |
| 122 | + |
| 123 | +That's it! After not more than a few minutes, you should be able to see your site at http://spring-projects.github.io/{your-spring-project} |
| 124 | + |
| 125 | + |
| 126 | +# How to keep common gh-pages content up to date |
| 127 | + |
| 128 | +Once you've set up your project's gh-pages infrastructure above, you'll get notified whenever |
| 129 | +changes are made to the shared gh-pages project. Actually, _your project_ will get notified, |
| 130 | +because a webhook configured on the gh-pages project will fire that ultimately creates a new |
| 131 | +issue in your project's GH Issues. |
| 132 | +> Yeah, it would have been nice to do proper pull requests instead of issues, but this arrangement |
| 133 | +with gh-pages branches and upstreams isn't based on forking. That means pull requests are no can do. |
| 134 | +This also means that if your project doesn't have issues turned on, you won't get notified! So you |
| 135 | +might consider doing that if you haven't already. |
| 136 | + |
| 137 | +In any case, whether or not you get notified via the issue coming in from the webhook, sync'ing |
| 138 | +up to the latest from the shared gh-pages project is easy enough: |
| 139 | + |
| 140 | +> This assumes you've got the `gh-pages-upstream` remote set up, per the instructions in sections |
| 141 | +above. |
| 142 | + |
| 143 | + git checkout gh-pages |
| 144 | + git pull --no-ff gh-pages-upstream gh-pages |
0 commit comments