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

README version for LibrePlanet 2019

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

# 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 **used to** be 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 by doing:
  * git checkout master
  * git pull
* 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.
* Make your edits. (See site structure and 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 by doing:
  * git checkout master
  * git merge BRANCHNAME
* Push master by doing:
  * 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 by doing:
  * git checkout stable
  * git merge master
  * git push
* Your edits are now live and visible at libreplanet.org/YEAR

# SECTION 2: SITE STRUCTURE

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".

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 (<https://ricketyspace.net/lpschedule-generator/>), as well as a local checkout of the SVN repository that contains brains.

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.

# SECTION 3: EDITING INSTRUCTIONS

To change content on existing pages, use your favorite text editor.

Here are specific instructions for more complex editing tasks:

## Editing the schedule or bios pages

The workflow for this is Edit the Brains page with the schedule, then run a script to convert it into HTML and dump it into your checkout of the repo, then push that change up to the Web like any other edit.

See instructions at <https://ricketyspace.net/lpschedule-generator> for installing and running the script. The source files are stored in Brains in markdown but with special tags, so that you can edit them without needing to know this whole process. The jinja2 templates are stored in the the Web site's git repo at assets/templates.

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.

## 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="/2019/includes/header.html"-->
<!--#include virtual="/2019/includes/banner.html"-->
<!--#include virtual="/2019/includes/sidebar.html"-->
<!--#include virtual="/2019/includes/footer.html"-->
<!--#include virtual="/2019/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 `/2019/includes/` & use SSI to include it in the page.

Use `/2019/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.

## Using Markdown

Static pages can be edited using markdown by creating a index.mdwn file in the appropriate subdirectory (e.g. ./fun/index.mdwn) and running 'make wikipages'. Note that the .mdwn files should have the ```<!--#include...``` lines in place, everything else being regular markdown. It is a requirement to have the python-markdown package installed to run 'make wikipages'. To add this functionality to new pages, edit the Makefile. Also note that the index.html in those directories would be generated from the mdwn file and should not be edited directly.

## Modifying top-right corner

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

*For register now*

Include `register-now.html`

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

*For join LP list form*

Include `join-list.html`

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


# SECTION 4: 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
a2enmod rewrite
```

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 lp2019.libreplanet.org
```

*Test*

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

# SECTION 5: TROUBLESHOOTING
* I'm doing everything right, but the Web site isn't updating.

Ask the tech team to look at the git hook that publishes to the live site. When you push to the git repository, this hook is supposed to update what is actually served on the Internet to match the repo.

* The website isn't loading! What?

It might be a permissions issue. Try cd / ls -lad to check permissions. If they are not right, chmod 711 . should fix it
Commit	Line	Data
6ca5bddc	1	README version for LibrePlanet 2019
	2
	3	Heads up: to edit the Web site, you'll need a basic-to-intermediate understanding of HTML, git, and command line.
	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 used to be 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	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 (<https://ricketyspace.net/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
	39
	40	To change content on existing pages, use your favorite text editor.
	41
	42	Here are specific instructions for more complex editing tasks:
	43
	44	## Editing the schedule or bios pages
	45
	46	The workflow for this is Edit the Brains page with the schedule, then run a script to convert it into HTML and dump it into your checkout of the repo, then push that change up to the Web like any other edit.
	47
	48	See instructions at <https://ricketyspace.net/lpschedule-generator> for installing and running the script. The source files are stored in Brains in markdown but with special tags, so that you can edit them without needing to know this whole process. The jinja2 templates are stored in the the Web site's git repo at assets/templates.
	49
	50	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.
	51
	52	## Creating a New Page
	53
	54	Boilerplate
	55
	56	Add the following to your new page (it should remain commented out, as that is the syntax for SSI):
	57
	58	```
	59	<!--#include virtual="/2019/includes/header.html"-->
	60	<!--#include virtual="/2019/includes/banner.html"-->
	61	<!--#include virtual="/2019/includes/sidebar.html"-->
	62	<!--#include virtual="/2019/includes/footer.html"-->
	63	<!--#include virtual="/2019/includes/close.html"-->
	64	```
65
66	This will include the header, banner, sidebar, footer and closing tags
67	saving you from duplicating HTML.
68
69	If JS is needed for a page, then create a file, containing the JS
70	includes, in `/2019/includes/` & use SSI to include it in the page.
71
72	Use `/2019/includes/boilerplate.html` to start a new page.
73
74	Add Your Markup
75
76	Add HTML markup in-between the sidebar and footer includes.
77
78	Enable SSI
79
80	Files that contain include directives must be marked as executable
81	otherwise Apache will not parse them. (The directive `XBitHack on` in the .conf file pasted above enables this behavior).
82
83	To mark a file as executable, run:
84
85	```
86	chmod +x foo.html
87	```
88
89	Replace `foo.html` with the desired file name.
90
91	## Using Markdown
92
93	Static pages can be edited using markdown by creating a index.mdwn file in the appropriate subdirectory (e.g. ./fun/index.mdwn) and running 'make wikipages'. Note that the .mdwn files should have the ```<!--#include...``` lines in place, everything else being regular markdown. It is a requirement to have the python-markdown package installed to run 'make wikipages'. To add this functionality to new pages, edit the Makefile. Also note that the index.html in those directories would be generated from the mdwn file and should not be edited directly.
94
95	## Modifying top-right corner
96
97	In the `/2019/includes/banner.html` find the `...#top-right-desktop
98	start...` section.
99
100	For register now
101
102	Include `register-now.html`
103
104	<!-- #top-right-desktop start -->
105	<!--#include virtual="/2019/includes/register-now.html"-->
106	<!-- #top-right-desktop end -->
107
108	For join LP list form
109
110	Include `join-list.html`
111
112	<!-- #top-right-desktop start -->
113	<!--#include virtual="/2019/includes/join-list.html"-->
114	<!-- #top-right-desktop end -->
115
116
117	# SECTION 4: SETTING UP A LOCAL DEVELOPMENT ENVIRONMENT
118
119	Apache is required in order to replicate the appearance of the website
120	on the live and staging servers on your machine. If you don't want to
121	install Apache, you can still work on the site, you just won't be able
122	to see what it looks like until you push to the remote.
123
124	Modifying Apache's configuration files and running its executables
125	typically requires root access. So, you will most likely need to run
126	the commands below as the root user using `sudo`.
127
128	Enable server-side include module
129
130	```
131	a2enmod include
132	a2enmod rewrite
133	```
134
135	If this doesn't work, you may not have Apache installed. Install the
136	package apache2 from your package manager.
137
138	Create virtual host
139
140	Create a new file called libreplanet (libreplanet.conf for Apache 2.4) in `/etc/apache2/sites-available` with the following contents:
141
142	```
143	<VirtualHost *:80>
144	RewriteEngine on
145	ServerName local-dev.libreplanet.org
146	ServerAdmin webmaster@localhost
147	DocumentRoot /local-path/path-to-site
148	<Directory /local-path/path-to-site/>
149	Options Indexes FollowSymLinks MultiViews
150	AllowOverride All
151	Require all granted
152	Order deny,allow
153	deny from none
154	allow from all
155	SSILegacyExprParser on
156	Options +Includes
157	XBitHack on
9b8b44d0	158	</Directory>
6ca5bddc	159	ErrorLog /home/owner/libreplanet-static/logs/error.log
	160	CustomLog /home/owner/libreplanet-static/access.log combined
	161	</VirtualHost>
	162	```
	163
	164	Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local
	165	git repository.
	166
	167	Enable virtual host
	168
	169	```
	170	a2ensite your-virtual-host
	171	```
	172
	173	Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet).
	174
	175	Restart Apache
	176
	177	```
	178	service apache2 restart
	179	```
	180
	181	Edit your hosts file
	182
	183	Edit your system's `/etc/hosts` file and add the following to the bottom:
	184
	185	```
	186	127.0.0.1 lp2019.libreplanet.org
	187	```
	188
	189	Test
	190
	191	Visit <http://lp2019.libreplanet.org/2019> in your web browser. If
	192	everything is configured properly, you will see the LibrePlanet 2019
	193	site, complete with header, sidebar, and footer.
	194
	195	# SECTION 5: TROUBLESHOOTING
	196	* I'm doing everything right, but the Web site isn't updating.
	197
	198	Ask the tech team to look at the git hook that publishes to the live site. When you push to the git repository, this hook is supposed to update what is actually served on the Internet to match the repo.
	199
	200	* The website isn't loading! What?
	201
	202	It might be a permissions issue. Try cd / ls -lad to check permissions. If they are not right, chmod 711 . should fix it