2016/README.md

   1 LibrePlanet 2016
   2 ================
   3
   4 This is the static HTML site for LibrePlanet 2016.  Read on for
   5 instructions on how to setup your development environment.
   6
   7 The repository has a master (development) branch and a stable
   8 (live) branch. To work on it, you'll edit your checkout of the
   9 master branch until you are satisfied, push it to the master
  10 branch on the Web server (<http://wiki-dev0.libreplanet.org>),
  11 make sure it works well and make sure it works well. Then
  12 you'll copy it over to your checkout of the stable branch,
  13 then push that to the stable branch on the Web server
  14 (<http://libreplanet.org>).
  15
  16 Setting Up Apache
  17 -----------------
  18
  19 Apache is required in order to replicate the appearance of the website
  20 on the live and staging servers on your machine. If you don't want to
  21 install Apache, you can still work on the site, you just won't be able
  22 to see what it looks like until you push to the remote.
  23
  24 Modifying Apache's configuration files and running its executables
  25 typically requires root access.  So, you will most likely need to run
  26 the commands below as the root user using `sudo`.
  27
  28 ### Enable server-side include module
  29
  30 ```
  31 a2enmod include
  32 ```
  33
  34 If this doesn't work, you may not have Apache installed. Install the
  35 package apache2 from your package manager.
  36
  37 ### Create virtual host
  38
  39 Create a new file called libreplanet (libreplanet.conf for Apache 2.4) in `/etc/apache2/sites-available` with the following contents:
  40
  41 ```
  42 <VirtualHost *:80>
  43 RewriteEngine on
  44         ServerName local-dev.libreplanet.org
  45         ServerAdmin webmaster@localhost
  46         DocumentRoot /local-path/path-to-site
  47         <Directory /local-path/path-to-site/>
  48             Options Indexes FollowSymLinks MultiViews
  49             AllowOverride All
  50             Require all granted
  51             Order deny,allow
  52             deny from none
  53             allow from all
  54             SSILegacyExprParser on
  55             Options +Includes
  56             XBitHack on
  57         </Directory>
  58         ErrorLog /home/owner/libreplanet-static/logs/error.log
  59         CustomLog /home/owner/libreplanet-static/access.log combined
  60 </VirtualHost>
  61 ```
  62
  63 Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local
  64 git repository.
  65
  66 ### Enable virtual host
  67
  68 ```
  69 a2ensite your-virtual-host
  70 ```
  71
  72 Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet).
  73
  74 ### Restart Apache
  75
  76 ```
  77 service apache2 restart
  78 ```
  79
  80 ### Edit your hosts file
  81
  82 Edit your system's `/etc/hosts` file and add the following to the bottom:
  83
  84 ```
  85 127.0.0.1 lp2016.libreplanet.org
  86 ```
  87
  88 ### Test
  89
  90 Visit <http://lp2016.libreplanet.org/2016> in your web browser.  If
  91 everything is configured properly, you will see the LibrePlanet 2016
  92 site, complete with header, sidebar, and footer.
  93
  94 Creating a New Page
  95 -------------------
  96
  97 ### Boilerplate
  98
  99 Add the following to your new page (it should remain commented out, as that is the syntax for SSI):
 100
 101 ```
 102 <!--#include virtual="/2016/includes/header.html"-->
 103 <!--#include virtual="/2016/includes/banner.html"-->
 104 <!--#include virtual="/2016/includes/sidebar.html"-->
 105 <!--#include virtual="/2016/includes/footer.html"-->
 106 <!--#include virtual="/2016/includes/close.html"-->
 107 ```
 108
 109 This will include the header, banner, sidebar, footer and closing tags
 110 saving you from duplicating HTML.
 111
 112 If JS is needed for a page, then create a file, containing the JS
 113 includes, in `/2016/includes/` & use SSI to include it in the page.
 114
 115 Use `/2016/includes/boilerplate.html` to start a new page.
 116
 117 ### Add Your Markup
 118
 119 Add HTML markup in-between the sidebar and footer includes.
 120
 121 ### Enable SSI
 122
 123 Files that contain include directives must be marked as executable
 124 otherwise Apache will not parse them.  (The directive `XBitHack on` in the .conf file pasted above enables this behavior).
 125
 126 To mark a file as executable, run:
 127
 128 ```
 129 chmod +x foo.html
 130 ```
 131
 132 Replace `foo.html` with the desired file name.
 133
 134 Schedule Markup
 135 ---------------
 136
 137 ### Program Day
 138
 139     <article id="DAY-program" class="program-day"> <!-- DAY program start -->
 140       <header class="program-day-header">
 141         <hgroup>
 142           <h2>Saturday, March DD
 143             <a class="btn btn-default btn-xs" role="button"
 144                data-toggle="collapse" aria-expanded="false"
 145                aria-controls="DAY-timeslots"
 146                href="#DAY-timeslots">
 147               &#x2193;
 148             </a>
 149           </h2>
 150         </hgroup>
 151       </header>
 152       <div class="collapse in" id="DAY-timeslots"> <!-- DAY-timeslots start -->
 153         <!-- Time slots come here. See next section (Time slot) -->
 154       </div> <!-- DAY-timeslots end -->
 155     </article>
 156
 157 Replace `DAY` by the day of the program (`sat` / `sun`).
 158
 159 ### Time slot
 160
 161 #### sessions
 162
 163         <article id="DAY-tsM" class="program-timeslot"> <!-- DAY-tsM start -->
 164           <header class="program-timeslot-header">
 165             <hgroup>
 166               <h2>TIME - Timeslot Description
 167                 <a class="btn btn-default btn-xs" role="button"
 168                         data-toggle="collapse" aria-expanded="false"
 169                         aria-controls="DAY-tsM-sessions"
 170                         href="#DAY-tsM-sessions">
 171                   &#x2193;
 172                 </a>
 173               </h2>
 174             </hgroup>
 175           </header>
 176           <div class="collapse in"
 177                id="DAY-tsM-sessions"> <!-- DAY-tsM-sessions start -->
 178              <!-- Sessions come here. See next section (Session). -->
 179           </div> <!-- DAY-tsM-sessions end -->
 180         </article> <!-- DAY-tsM end -->
 181
 182 Replace `DAY` by the day of the program (`sat`/`sun`) and `M` by time
 183 slot number.
 184
 185 #### break
 186
 187         <article id="DAY-ts-bM"
 188                  class="program-timeslot-break"> <!-- DAY-ts-bM start -->
 189           <header class="program-timeslot-break-header">
 190             <hgroup>
 191               <h2>TIME: Break</h2>
 192             </hgroup>
 193           </header>
 194         </article> <!-- DAY-ts-bM end -->
 195
 196 Replace `DAY` by the day of the program (`sat`/`sun`) and `M` by break
 197 number.
 198
 199 ### Session
 200
 201             <section id="DAY-tsM-sN"
 202                      class="program-session"> <!-- DAY-tsM-sN start -->
 203               <header class="program-session-header">
 204                 <h2>Session Heading</h2>
 205               </header>
 206               <!-- Session "always visible" Content -->
 207               <button class="btn btn-default btn-xs" role="button"
 208                       data-toggle="collapse" aria-expanded="false"
 209                       aria-controls="DAY-tsM-sN-collapse"
 210                       data-target="#DAY-tsM-sN-collapse">
 211                 Details
 212               </button>
 213               <div class="collapse in" id="DAY-tsM-sN-collapse">
 214                 <!-- Session Collapsible Content  -->
 215               </div>
 216             </section> <!-- DAY-tsM-sN end -->
 217
 218 Replace `DAY` by the day of the program (`sat`/`sun`), `M` by the time slot number and `N` by the session number.
 219
 220 Deploying to Staging/Live Servers
 221 ---------------------------------
 222
 223 A system of git hooks automates deployment to the staging and live
 224 servers.  When you push to the `master` branch, the site is deployed
 225 to <http://wiki-dev0.libreplanet.org/2016>.  When you push to the
 226 `stable` branch, the site is deployed to <http://libreplanet.org>.
 227
 228 When you're happy with the state of the master branch and want to
 229 deploy live, do the following:
 230
 231 ```
 232 git checkout stable
 233 git merge master
 234 git push
 235 ```
 236
 237 This merges the master branch with the stable branch, updates the
 238 remote repository on the git server, and triggers a deploy to
 239 <http://libreplanet.org>.
 240
 241 CSS and JavaScript
 242 ------------------
 243
 244 This site is built with:
 245
 246 * [Bootstrap 3.3.5](https://github.com/twbs/bootstrap/releases/download/v3.3.5/bootstrap-3.3.5-dist.zip)
 247 * [jQuery 1.11.1](http://code.jquery.com/jquery-1.11.3.js)