2017/README.md

   1 README version for LibrePlanet 2017
   2
   3 Heads up: to edit the Web site, you'll need a basic-to-intermediate understanding of HTML and git.
   4
   5 ##### SECTION 1: DEVELOPMENT WORKFLOW #####
   6
   7 The actual LIVE site, visible at libreplanet.org/YEAR, is served from the "stable" branch of the git repository using a git hook. There is also a development branch called "master" which we use to preview edits on the Web. The master branch is served to the Web at http://wiki-dev0.libreplanet.org/YEAR and publicly visible, but not linked to.
   8
   9 Full workflow to make, test and deploy an edit.
  10 -----------------
  11
  12 * Check out the master branch and make sure it is up to date with origin/master by doing:
  13   * git checkout master
  14   * git pull
  15 * Is this a large edit or a small edit? If it is small, edit, work in master. If this is a large edit that will take longer than a day, make a new branch based on the master branch and work there.
  16 * Make your edits. (See site structure and instructions for editing content below.)
  17 * Optionally, test them on your computer with a local development environment. (See instructions below for setting up your development environment).
  18 * If you are working on your own branch created for your edit, merge, your branch into master by doing:
  19   * git checkout master
  20   * git merge BRANCHNAME
  21 * Push master by doing:
  22   * git push
  23 * Review the edited version of the site at http://wiki-dev0.libreplanet.org/YEAR. You can share this with others.
  24 * When you are satisfied, merge master into stable and then push stable by doing:
  25   * git checkout stable
  26   * git merge master
  27   * git push
  28 * Your edits are now live and visible at libreplanet.org/YEAR
  29
  30 ##### SECTION 2: SITE STRUCTURE #####
  31
  32 The site is made up of HTML files, each representing part of a page (sidebar, content, footer, etc.). When a browser visits the site, the server finds the core HTML file for the page (for example, the core file for https://www.libreplanet.org/YEAR/getting-around is /YEAR/getting-around/index.html in the repo), then reads special comments in that file to which instruct it to pull various other HTML files in to produce a complete page, using an Apache feature called SSI. To edit part of a page, you will need to find out which HTML file contains the element in question. Do this by navigating to core HTML file and exploring the comments that start with "#include".
  33
  34 ##### SECTION 3: EDITING INSTRUCTIONS #####
  35
  36 To change content on existing pages, simply use your favorite text editor.
  37
  38 This site is built with [Bootstrap 3.3.5](https://github.com/twbs/bootstrap/releases/download/v3.3.5/bootstrap-3.3.5-dist.zip) and [jQuery 1.11.1](http://code.jquery.com/jquery-1.11.3.js) but you do not need to understand either of these technologies to make minor content edits to the site.
  39
  40 Creating a New Page
  41 -------------------
  42
  43 *Boilerplate*
  44
  45 Add the following to your new page (it should remain commented out, as that is the syntax for SSI):
  46
  47 ```
  48 <!--#include virtual="/2017/includes/header.html"-->
  49 <!--#include virtual="/2017/includes/banner.html"-->
  50 <!--#include virtual="/2017/includes/sidebar.html"-->
  51 <!--#include virtual="/2017/includes/footer.html"-->
  52 <!--#include virtual="/2017/includes/close.html"-->
  53 ```
  54
  55 This will include the header, banner, sidebar, footer and closing tags
  56 saving you from duplicating HTML.
  57
  58 If JS is needed for a page, then create a file, containing the JS
  59 includes, in `/2017/includes/` & use SSI to include it in the page.
  60
  61 Use `/2017/includes/boilerplate.html` to start a new page.
  62
  63 *Add Your Markup*
  64
  65 Add HTML markup in-between the sidebar and footer includes.
  66
  67 *Enable SSI*
  68
  69 Files that contain include directives must be marked as executable
  70 otherwise Apache will not parse them.  (The directive `XBitHack on` in the .conf file pasted above enables this behavior).
  71
  72 To mark a file as executable, run:
  73
  74 ```
  75 chmod +x foo.html
  76 ```
  77
  78 Replace `foo.html` with the desired file name.
  79
  80 Modifying top-right corner
  81 --------------------------
  82
  83 In the `/2017/includes/banner.html` find the `...#top-right-desktop
  84 start...` section.
  85
  86 *For register now*
  87
  88 Include `register-now.html`
  89
  90     <!-- #top-right-desktop start -->
  91     <!--#include virtual="/2017/includes/register-now.html"-->
  92     <!-- #top-right-desktop end -->
  93
  94 *For join LP list form*
  95
  96 Include `join-list.html`
  97
  98     <!-- #top-right-desktop start -->
  99     <!--#include virtual="/2017/includes/join-list.html"-->
 100     <!-- #top-right-desktop end -->
 101
 102
 103 ##### SECTION 4: SETTING UP A LOCAL DEVELOPMENT ENVIRONMENT #####
 104
 105 Apache is required in order to replicate the appearance of the website
 106 on the live and staging servers on your machine. If you don't want to
 107 install Apache, you can still work on the site, you just won't be able
 108 to see what it looks like until you push to the remote.
 109
 110 Modifying Apache's configuration files and running its executables
 111 typically requires root access.  So, you will most likely need to run
 112 the commands below as the root user using `sudo`.
 113
 114 *Enable server-side include module*
 115
 116 ```
 117 a2enmod include
 118 ```
 119
 120 If this doesn't work, you may not have Apache installed. Install the
 121 package apache2 from your package manager.
 122
 123 *Create virtual host*
 124
 125 Create a new file called libreplanet (libreplanet.conf for Apache 2.4) in `/etc/apache2/sites-available` with the following contents:
 126
 127 ```
 128 <VirtualHost *:80>
 129 RewriteEngine on
 130         ServerName local-dev.libreplanet.org
 131         ServerAdmin webmaster@localhost
 132         DocumentRoot /local-path/path-to-site
 133         <Directory /local-path/path-to-site/>
 134             Options Indexes FollowSymLinks MultiViews
 135             AllowOverride All
 136             Require all granted
 137             Order deny,allow
 138             deny from none
 139             allow from all
 140             SSILegacyExprParser on
 141             Options +Includes
 142             XBitHack on
 143         </Directory>
 144         ErrorLog /home/owner/libreplanet-static/logs/error.log
 145         CustomLog /home/owner/libreplanet-static/access.log combined
 146 </VirtualHost>
 147 ```
 148
 149 Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local
 150 git repository.
 151
 152 *Enable virtual host*
 153
 154 ```
 155 a2ensite your-virtual-host
 156 ```
 157
 158 Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet).
 159
 160 *Restart Apache*
 161
 162 ```
 163 service apache2 restart
 164 ```
 165
 166 *Edit your hosts file*
 167
 168 Edit your system's `/etc/hosts` file and add the following to the bottom:
 169
 170 ```
 171 127.0.0.1 lp2017.libreplanet.org
 172 ```
 173
 174 *Test*
 175
 176 Visit <http://lp2017.libreplanet.org/2017> in your web browser.  If
 177 everything is configured properly, you will see the LibrePlanet 2017
 178 site, complete with header, sidebar, and footer.