Commit | Line | Data |
---|---|---|
179bf9bc ZR |
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. | |
fcf95e6d | 4 | |
6ba4ea6c | 5 | # SECTION 1: DEVELOPMENT WORKFLOW |
fcf95e6d | 6 | |
60bc0202 | 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. |
fcf95e6d | 8 | |
79263a67 | 9 | Full workflow to make, test and deploy an edit. |
60bc0202 | 10 | ----------------- |
fcf95e6d | 11 | |
12268ed4 | 12 | * Check out the master branch and make sure it is up to date with origin/master by doing: |
60bc0202 | 13 | * git checkout master |
179bf9bc | 14 | * git pull |
12268ed4 | 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. |
79263a67 | 16 | * Make your edits. (See site structure and instructions for editing content below.) |
60bc0202 | 17 | * Optionally, test them on your computer with a local development environment. (See instructions below for setting up your development environment). |
12268ed4 | 18 | * If you are working on your own branch created for your edit, merge, your branch into master by doing: |
60bc0202 ZR |
19 | * git checkout master |
20 | * git merge BRANCHNAME | |
12268ed4 | 21 | * Push master by doing: |
60bc0202 ZR |
22 | * git push |
23 | * Review the edited version of the site at http://wiki-dev0.libreplanet.org/YEAR. You can share this with others. | |
12268ed4 | 24 | * When you are satisfied, merge master into stable and then push stable by doing: |
60bc0202 ZR |
25 | * git checkout stable |
26 | * git merge master | |
27 | * git push | |
179bf9bc | 28 | * Your edits are now live and visible at libreplanet.org/YEAR |
60bc0202 | 29 | |
6ba4ea6c | 30 | # SECTION 2: SITE STRUCTURE |
79263a67 ZR |
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 | ||
6ba4ea6c ZR |
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. |
35 | ||
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. | |
37 | ||
38 | # SECTION 3: EDITING INSTRUCTIONS | |
60bc0202 | 39 | |
b52f8dce | 40 | To change content on existing pages, use your favorite text editor. |
12268ed4 | 41 | |
6ba4ea6c ZR |
42 | Here are specific instructions for more complex editing tasks: |
43 | ||
6ba4ea6c ZR |
44 | ## Editing the schedule |
45 | ||
46 | 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. | |
fcf95e6d | 47 | |
b52f8dce ZR |
48 | ## Editing the bios page |
49 | ||
50 | 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. | |
51 | ||
52 | Please crop all photos of speakers too 100x100 px (200x200 px for keynotes) and then upload them to <http://static.fsf.org/nosvn/libreplanet/speaker-pics/>. Then include their URL in the bios page to embed them. | |
53 | ||
6ba4ea6c | 54 | ## Creating a New Page |
fcf95e6d | 55 | |
60bc0202 | 56 | *Boilerplate* |
fcf95e6d | 57 | |
58 | Add the following to your new page (it should remain commented out, as that is the syntax for SSI): | |
59 | ||
60 | ``` | |
61 | <!--#include virtual="/2017/includes/header.html"--> | |
62 | <!--#include virtual="/2017/includes/banner.html"--> | |
63 | <!--#include virtual="/2017/includes/sidebar.html"--> | |
64 | <!--#include virtual="/2017/includes/footer.html"--> | |
65 | <!--#include virtual="/2017/includes/close.html"--> | |
66 | ``` | |
67 | ||
68 | This will include the header, banner, sidebar, footer and closing tags | |
69 | saving you from duplicating HTML. | |
70 | ||
71 | If JS is needed for a page, then create a file, containing the JS | |
72 | includes, in `/2017/includes/` & use SSI to include it in the page. | |
73 | ||
74 | Use `/2017/includes/boilerplate.html` to start a new page. | |
75 | ||
60bc0202 | 76 | *Add Your Markup* |
fcf95e6d | 77 | |
78 | Add HTML markup in-between the sidebar and footer includes. | |
79 | ||
60bc0202 | 80 | *Enable SSI* |
fcf95e6d | 81 | |
82 | Files that contain include directives must be marked as executable | |
83 | otherwise Apache will not parse them. (The directive `XBitHack on` in the .conf file pasted above enables this behavior). | |
84 | ||
85 | To mark a file as executable, run: | |
86 | ||
87 | ``` | |
88 | chmod +x foo.html | |
89 | ``` | |
90 | ||
91 | Replace `foo.html` with the desired file name. | |
92 | ||
6ba4ea6c | 93 | ## Modifying top-right corner |
7ba5343a | 94 | |
95 | In the `/2017/includes/banner.html` find the `...#top-right-desktop | |
96 | start...` section. | |
97 | ||
60bc0202 | 98 | *For register now* |
7ba5343a | 99 | |
100 | Include `register-now.html` | |
101 | ||
102 | <!-- #top-right-desktop start --> | |
103 | <!--#include virtual="/2017/includes/register-now.html"--> | |
104 | <!-- #top-right-desktop end --> | |
105 | ||
60bc0202 | 106 | *For join LP list form* |
7ba5343a | 107 | |
108 | Include `join-list.html` | |
109 | ||
110 | <!-- #top-right-desktop start --> | |
111 | <!--#include virtual="/2017/includes/join-list.html"--> | |
112 | <!-- #top-right-desktop end --> | |
113 | ||
fcf95e6d | 114 | |
6ba4ea6c | 115 | # SECTION 4: SETTING UP A LOCAL DEVELOPMENT ENVIRONMENT |
60bc0202 ZR |
116 | |
117 | Apache is required in order to replicate the appearance of the website | |
118 | on the live and staging servers on your machine. If you don't want to | |
119 | install Apache, you can still work on the site, you just won't be able | |
120 | to see what it looks like until you push to the remote. | |
121 | ||
122 | Modifying Apache's configuration files and running its executables | |
123 | typically requires root access. So, you will most likely need to run | |
124 | the commands below as the root user using `sudo`. | |
125 | ||
126 | *Enable server-side include module* | |
127 | ||
128 | ``` | |
129 | a2enmod include | |
130 | ``` | |
131 | ||
132 | If this doesn't work, you may not have Apache installed. Install the | |
133 | package apache2 from your package manager. | |
134 | ||
135 | *Create virtual host* | |
136 | ||
137 | Create a new file called libreplanet (libreplanet.conf for Apache 2.4) in `/etc/apache2/sites-available` with the following contents: | |
138 | ||
139 | ``` | |
140 | <VirtualHost *:80> | |
141 | RewriteEngine on | |
142 | ServerName local-dev.libreplanet.org | |
143 | ServerAdmin webmaster@localhost | |
144 | DocumentRoot /local-path/path-to-site | |
145 | <Directory /local-path/path-to-site/> | |
146 | Options Indexes FollowSymLinks MultiViews | |
147 | AllowOverride All | |
148 | Require all granted | |
149 | Order deny,allow | |
150 | deny from none | |
151 | allow from all | |
152 | SSILegacyExprParser on | |
153 | Options +Includes | |
154 | XBitHack on | |
155 | </Directory> | |
156 | ErrorLog /home/owner/libreplanet-static/logs/error.log | |
157 | CustomLog /home/owner/libreplanet-static/access.log combined | |
158 | </VirtualHost> | |
159 | ``` | |
160 | ||
161 | Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local | |
162 | git repository. | |
163 | ||
164 | *Enable virtual host* | |
165 | ||
166 | ``` | |
167 | a2ensite your-virtual-host | |
168 | ``` | |
169 | ||
170 | Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet). | |
fcf95e6d | 171 | |
60bc0202 | 172 | *Restart Apache* |
fcf95e6d | 173 | |
174 | ``` | |
60bc0202 | 175 | service apache2 restart |
fcf95e6d | 176 | ``` |
177 | ||
60bc0202 | 178 | *Edit your hosts file* |
fcf95e6d | 179 | |
60bc0202 ZR |
180 | Edit your system's `/etc/hosts` file and add the following to the bottom: |
181 | ||
182 | ``` | |
183 | 127.0.0.1 lp2017.libreplanet.org | |
184 | ``` | |
fcf95e6d | 185 | |
60bc0202 | 186 | *Test* |
fcf95e6d | 187 | |
60bc0202 ZR |
188 | Visit <http://lp2017.libreplanet.org/2017> in your web browser. If |
189 | everything is configured properly, you will see the LibrePlanet 2017 | |
190 | site, complete with header, sidebar, and footer. |