1 README version for LibrePlanet 2017
3 Heads up: to edit the Web site, you'll need a basic-to-intermediate understanding of HTML and git.
5 # SECTION 1: DEVELOPMENT WORKFLOW
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.
9 Full workflow to make, test and deploy an edit.
12 * Check out the master branch and make sure it is up to date with origin/master by doing:
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:
20 * git merge BRANCHNAME
21 * Push master by doing:
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:
28 * Your edits are now live and visible at libreplanet.org/YEAR
30 # SECTION 2: SITE STRUCTURE
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".
34 The bios page and the sessions page are maintained through a special workflow to make it easy to have only one canonical copy edited by humans. That canonical copy is saved in brains (the FSF's internal wiki) in a special format. To update the sites' sessions page or bios page, you will need the lps_gen program installed on your computer (<http://pythonhosted.org/lpschedule-generator>), as well as a local checkout of the SVN repository that contains brains.
36 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.
38 # SECTION 3: EDITING INSTRUCTIONS
40 To change content on existing pages, simply use your favorite text editor.
42 Here are specific instructions for more complex editing tasks:
45 ## Editing the schedule
47 See instructions at <http://pythonhosted.org/lpschedule-generator>. For 2017, the jinja2 templates are stored in the the Web site's git repo at assets/templates.
49 ## Creating a New Page
53 Add the following to your new page (it should remain commented out, as that is the syntax for SSI):
56 <!--#include virtual="/2017/includes/header.html"-->
57 <!--#include virtual="/2017/includes/banner.html"-->
58 <!--#include virtual="/2017/includes/sidebar.html"-->
59 <!--#include virtual="/2017/includes/footer.html"-->
60 <!--#include virtual="/2017/includes/close.html"-->
63 This will include the header, banner, sidebar, footer and closing tags
64 saving you from duplicating HTML.
66 If JS is needed for a page, then create a file, containing the JS
67 includes, in `/2017/includes/` & use SSI to include it in the page.
69 Use `/2017/includes/boilerplate.html` to start a new page.
73 Add HTML markup in-between the sidebar and footer includes.
77 Files that contain include directives must be marked as executable
78 otherwise Apache will not parse them. (The directive `XBitHack on` in the .conf file pasted above enables this behavior).
80 To mark a file as executable, run:
86 Replace `foo.html` with the desired file name.
88 ## Modifying top-right corner
90 In the `/2017/includes/banner.html` find the `...#top-right-desktop
95 Include `register-now.html`
97 <!-- #top-right-desktop start -->
98 <!--#include virtual="/2017/includes/register-now.html"-->
99 <!-- #top-right-desktop end -->
101 *For join LP list form*
103 Include `join-list.html`
105 <!-- #top-right-desktop start -->
106 <!--#include virtual="/2017/includes/join-list.html"-->
107 <!-- #top-right-desktop end -->
110 # SECTION 4: SETTING UP A LOCAL DEVELOPMENT ENVIRONMENT
112 Apache is required in order to replicate the appearance of the website
113 on the live and staging servers on your machine. If you don't want to
114 install Apache, you can still work on the site, you just won't be able
115 to see what it looks like until you push to the remote.
117 Modifying Apache's configuration files and running its executables
118 typically requires root access. So, you will most likely need to run
119 the commands below as the root user using `sudo`.
121 *Enable server-side include module*
127 If this doesn't work, you may not have Apache installed. Install the
128 package apache2 from your package manager.
130 *Create virtual host*
132 Create a new file called libreplanet (libreplanet.conf for Apache 2.4) in `/etc/apache2/sites-available` with the following contents:
137 ServerName local-dev.libreplanet.org
138 ServerAdmin webmaster@localhost
139 DocumentRoot /local-path/path-to-site
140 <Directory /local-path/path-to-site/>
141 Options Indexes FollowSymLinks MultiViews
147 SSILegacyExprParser on
151 ErrorLog /home/owner/libreplanet-static/logs/error.log
152 CustomLog /home/owner/libreplanet-static/access.log combined
156 Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local
159 *Enable virtual host*
162 a2ensite your-virtual-host
165 Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet).
170 service apache2 restart
173 *Edit your hosts file*
175 Edit your system's `/etc/hosts` file and add the following to the bottom:
178 127.0.0.1 lp2017.libreplanet.org
183 Visit <http://lp2017.libreplanet.org/2017> in your web browser. If
184 everything is configured properly, you will see the LibrePlanet 2017
185 site, complete with header, sidebar, and footer.