fcf95e6d |
1 | LibrePlanet 2017 |
2 | ================ |
3 | |
4 | This is the static HTML site for LibrePlanet 2017. 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 lp2017.libreplanet.org |
86 | ``` |
87 | |
88 | ### Test |
89 | |
90 | Visit <http://lp2017.libreplanet.org/2017> in your web browser. If |
91 | everything is configured properly, you will see the LibrePlanet 2017 |
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="/2017/includes/header.html"--> |
103 | <!--#include virtual="/2017/includes/banner.html"--> |
104 | <!--#include virtual="/2017/includes/sidebar.html"--> |
105 | <!--#include virtual="/2017/includes/footer.html"--> |
106 | <!--#include virtual="/2017/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 `/2017/includes/` & use SSI to include it in the page. |
114 | |
115 | Use `/2017/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 | ↓ |
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 | ↓ |
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/2017>. 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) |