Adding theme paragraph.

[libreplanet-static.git] / 2017 / README.md

README version for LibrePlanet 2017

Heads up: to edit the Web site, you'll need a basic-to-intermediate understanding of HTML and git.

##### SECTION 1: DEVELOPMENT WORKFLOW #####

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.

Full workflow to make, test and deploy an edit
-----------------

* Check out the master branch and make sure it is up to date with origin/master.
  * git checkout master
  * git pull
* If 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.
* Make your edits. (See instructions for editing content below.)
* Optionally, test them on your computer with a local development environment. (See instructions below for setting up your development environment).
* If you are working on your own branch created for your edit, merge, your branch into master.
  * git checkout master
  * git merge BRANCHNAME
* Push master
  * git push
* Review the edited version of the site at http://wiki-dev0.libreplanet.org/YEAR. You can share this with others.
* When you are satisfied, merge master into stable and then push stable.
  * git checkout stable
  * git merge master
  * git push
* Your edits are now live and visible at libreplanet.org/YEAR

##### SECTION 2: EDITING INSTRUCTIONS #####

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.

Creating a New Page
-------------------

*Boilerplate*

Add the following to your new page (it should remain commented out, as that is the syntax for SSI):

```
<!--#include virtual="/2017/includes/header.html"-->
<!--#include virtual="/2017/includes/banner.html"-->
<!--#include virtual="/2017/includes/sidebar.html"-->
<!--#include virtual="/2017/includes/footer.html"-->
<!--#include virtual="/2017/includes/close.html"-->
```

This will include the header, banner, sidebar, footer and closing tags
saving you from duplicating HTML.

If JS is needed for a page, then create a file, containing the JS
includes, in `/2017/includes/` & use SSI to include it in the page.

Use `/2017/includes/boilerplate.html` to start a new page.

*Add Your Markup*

Add HTML markup in-between the sidebar and footer includes.

*Enable SSI*

Files that contain include directives must be marked as executable
otherwise Apache will not parse them.  (The directive `XBitHack on` in the .conf file pasted above enables this behavior).

To mark a file as executable, run:

```
chmod +x foo.html
```

Replace `foo.html` with the desired file name.

Modifying top-right corner
--------------------------

In the `/2017/includes/banner.html` find the `...#top-right-desktop
start...` section.

*For register now*

Include `register-now.html`

    <!-- #top-right-desktop start -->
    <!--#include virtual="/2017/includes/register-now.html"-->
    <!-- #top-right-desktop end -->

*For join LP list form*

Include `join-list.html`

    <!-- #top-right-desktop start -->
    <!--#include virtual="/2017/includes/join-list.html"-->
    <!-- #top-right-desktop end -->


##### SECTION 3: SETTING UP A LOCAL DEVELOPMENT ENVIRONMENT #####

Apache is required in order to replicate the appearance of the website
on the live and staging servers on your machine. If you don't want to
install Apache, you can still work on the site, you just won't be able
to see what it looks like until you push to the remote.

Modifying Apache's configuration files and running its executables
typically requires root access.  So, you will most likely need to run
the commands below as the root user using `sudo`.

*Enable server-side include module*

```
a2enmod include
```

If this doesn't work, you may not have Apache installed. Install the
package apache2 from your package manager.

*Create virtual host*

Create a new file called libreplanet (libreplanet.conf for Apache 2.4) in `/etc/apache2/sites-available` with the following contents:

```
<VirtualHost *:80>
RewriteEngine on
        ServerName local-dev.libreplanet.org
        ServerAdmin webmaster@localhost
        DocumentRoot /local-path/path-to-site
        <Directory /local-path/path-to-site/>
            Options Indexes FollowSymLinks MultiViews
            AllowOverride All
            Require all granted
            Order deny,allow
            deny from none
            allow from all
            SSILegacyExprParser on
            Options +Includes
            XBitHack on
        </Directory>
        ErrorLog /home/owner/libreplanet-static/logs/error.log
        CustomLog /home/owner/libreplanet-static/access.log combined
</VirtualHost>
```

Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local
git repository.

*Enable virtual host*

```
a2ensite your-virtual-host
```

Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet).

*Restart Apache*

```
service apache2 restart
```

*Edit your hosts file*

Edit your system's `/etc/hosts` file and add the following to the bottom:

```
127.0.0.1 lp2017.libreplanet.org
```

*Test*

Visit <http://lp2017.libreplanet.org/2017> in your web browser.  If
everything is configured properly, you will see the LibrePlanet 2017
site, complete with header, sidebar, and footer.