diff options
Diffstat (limited to 'docs')
28 files changed, 341 insertions, 344 deletions
diff --git a/docs/customising/config.md b/docs/customising/config.md index c03e0fc9e..a20a9f7df 100644 --- a/docs/customising/config.md +++ b/docs/customising/config.md @@ -14,7 +14,7 @@ title: Configuration The alaveteli code ships with an example configuration file: `config/general.yml-example`. -As part of the [installation process]({{ site.baseurl }}docs/installing/ ), the +As part of the [installation process]({{ page.baseurl }}/docs/installing/ ), the example file gets copied to `config/general.yml`. You **must** edit this file to suit your needs. @@ -208,7 +208,7 @@ indentation correct. If in doubt, look at the examples already in the file, and <a name="theme_urls"><code>THEME_URLS</code></a> </dt> <dd> - URLs of <a href="{{ site.baseurl }}docs/customising/themes/">themes</a> to download and use + URLs of <a href="{{ page.baseurl }}/docs/customising/themes/">themes</a> to download and use (when running the <code>rails-post-deploy</code> script). The earlier in the list means the templates have a higher priority. <div class="more-info"> @@ -228,7 +228,7 @@ THEME_URLS: <a name="theme_branch"><code>THEME_BRANCH</code></a> </dt> <dd> - When <code>rails-post-deploy</code> installs the <a href="{{ site.baseurl }}docs/customising/themes/">themes</a>, + When <code>rails-post-deploy</code> installs the <a href="{{ page.baseurl }}/docs/customising/themes/">themes</a>, it will try the theme branch first, but only if you've set <code>THEME_BRANCH</code> to be true. If the branch doesn't exist it will fall back to using a tagged version specific to your installed alaveteli version, and if that doesn't exist it will @@ -353,9 +353,9 @@ THEME_URLS: </dt> <dd> Is this a - <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary__link">staging</a> or - <a href="{{site.baseurl}}docs/glossary/#development" class="glossary__link">development</a> site? - If not, it's a live <a href="{{site.baseurl}}docs/glossary/#production" class="glossary__link">production</a> + <a href="{{ page.baseurl }}/docs/glossary/#staging" class="glossary__link">staging</a> or + <a href="{{ page.baseurl }}/docs/glossary/#development" class="glossary__link">development</a> site? + If not, it's a live <a href="{{ page.baseurl }}/docs/glossary/#production" class="glossary__link">production</a> site. This setting controls whether or not the <code>rails-post-deploy</code> script will create the file <code>config/rails_env.rb</code> file to force Rails into production environment. @@ -506,7 +506,7 @@ THEME_URLS: </dt> <dd> Details for the - <a href="{{site.baseurl}}docs/glossary/#emergency" class="glossary__link">emergency user</a>. + <a href="{{ page.baseurl }}/docs/glossary/#emergency" class="glossary__link">emergency user</a>. <p> This is useful for creating the initial admin users for your site: <ul> @@ -518,7 +518,7 @@ THEME_URLS: </p> <p> For details of this process, see - <a href="{{site.baseurl}}docs/installing/next_steps/#create-a-superuser-admin-account">creating + <a href="{{ page.baseurl }}/docs/installing/next_steps/#create-a-superuser-admin-account">creating a superuser account</a>. </p> <div class="more-info"> @@ -557,7 +557,7 @@ THEME_URLS: <a name="incoming_email_domain"><code>INCOMING_EMAIL_DOMAIN</code></a> </dt> <dd> - Your email domain for incoming mail. See also <a href="{{ site.baseurl }}docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. + Your email domain for incoming mail. See also <a href="{{ page.baseurl }}/docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. <div class="more-info"> <p>Example:</p> <ul class="examples"> @@ -575,7 +575,7 @@ THEME_URLS: <a name="incoming_email_prefix"><code>INCOMING_EMAIL_PREFIX</code></a> </dt> <dd> - An optional prefix to help you distinguish FOI requests. See also <a href="{{ site.baseurl }}docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. + An optional prefix to help you distinguish FOI requests. See also <a href="{{ page.baseurl }}/docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. <div class="more-info"> <p>Example:</p> <ul class="examples"> @@ -625,7 +625,7 @@ THEME_URLS: <a name="contact_name"><code>CONTACT_NAME</code></a> </dt> <dd> - Email "from" details. See also <a href="{{ site.baseurl }}docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. + Email "from" details. See also <a href="{{ page.baseurl }}/docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. <div class="more-info"> <p>Examples:</p> <ul class="examples"> @@ -644,7 +644,7 @@ THEME_URLS: <a name="track_sender_name"><code>TRACK_SENDER_NAME</code></a> </dt> <dd> - Email "from" details for track messages. See also <a href="{{ site.baseurl }}docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. + Email "from" details for track messages. See also <a href="{{ page.baseurl }}/docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. <div class="more-info"> <p>Examples:</p> <ul class="examples"> @@ -700,7 +700,7 @@ EXCEPTION_NOTIFICATIONS_TO: <a name="forward_nonbounce_responses_to"><code>FORWARD_NONBOUNCE_RESPONSES_TO</code></a> </dt> <dd> - The email address to which non-bounce responses should be forwarded. See also <a href="{{ site.baseurl }}docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. + The email address to which non-bounce responses should be forwarded. See also <a href="{{ page.baseurl }}/docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. <div class="more-info"> <p>Example:</p> <ul class="examples"> diff --git a/docs/customising/index.md b/docs/customising/index.md index 19100ad20..bd1247894 100644 --- a/docs/customising/index.md +++ b/docs/customising/index.md @@ -15,7 +15,7 @@ title: Customising ## Configuration settings You can customise much of Alaveteli's behaviour just by editing the configuration -file. This [complete list of Alaveteli's config settings]({{ site.baseurl }}docs/customising/config/) +file. This [complete list of Alaveteli's config settings]({{ page.baseurl }}/docs/customising/config/) shows the sort of things you can control in this way. <!-- TODO key settings --> @@ -24,7 +24,7 @@ shows the sort of things you can control in this way. It's common to want to change the basic appearance of the site. Although you can simply edit the default templates and CSS to do this, we **strongly -recommend** that you [create a theme]({{ site.baseurl }}docs/customising/themes/). +recommend** that you [create a theme]({{ page.baseurl }}/docs/customising/themes/). Themes do not need to be especially complex, but they allow your changes to work alongside the core code, which you can then update (when new releases or @@ -32,13 +32,13 @@ updates become available). ## Need Alaveteli in a different language? -No problem! See the [information about translating Alaveteli]({{ site.baseurl }}docs/customising/translation/). +No problem! See the [information about translating Alaveteli]({{ page.baseurl }}/docs/customising/translation/). ## Complex changes If you are a developer (or you have a team of programmers available) you can add any customisation that you want. But it's important to do this without breaking the core code, so that you can accept new releases with updates. -There's more detail in the [page about themes]({{ site.baseurl }}docs/customising/themes/). +There's more detail in the [page about themes]({{ page.baseurl }}/docs/customising/themes/). -See also the [documentation for developers]({{ site.baseurl }}docs/developers/). +See also the [documentation for developers]({{ page.baseurl }}/docs/developers/). diff --git a/docs/customising/states.md b/docs/customising/states.md index 7b89ef45d..0bc934082 100644 --- a/docs/customising/states.md +++ b/docs/customising/states.md @@ -6,16 +6,16 @@ title: States of requests # Request states <p class="lead"> - A <a href="{{site.baseurl}}docs/glossary/#request" class="glossary__link">request</a> + A <a href="{{ page.baseurl }}/docs/glossary/#request" class="glossary__link">request</a> passes through different <strong>states</strong> as it is processed. These may vary from one jurisdiction to another. </p> The request states are defined in the Alaveteli code, and we recommend you use -them (provided they match the <a href="{{ site.baseurl }}docs/glossary/#foi" +them (provided they match the <a href="{{ page.baseurl }}/docs/glossary/#foi" class="glossary__link">FOI law</a> in your own jurisdiction). But if you do need to customise them, you can — see -<a href="{{ site.baseurl }}docs/customising/themes/#customising-the-request-states">Customising the request states</a> for details. +<a href="{{ page.baseurl }}/docs/customising/themes/#customising-the-request-states">Customising the request states</a> for details. ## WhatDoTheyKnow example @@ -24,7 +24,7 @@ may be in any of the states described below. Note that your site doesn't need to use the same states as WhatDoTheyKnow does. For example, Kosovo's instance uses slightly different states: see -[this comparison of their differences]({{ site.baseurl }}docs/customising/states_informatazyrtare/). +[this comparison of their differences]({{ page.baseurl }}/docs/customising/states_informatazyrtare/). ### States diff --git a/docs/customising/states_informatazyrtare.md b/docs/customising/states_informatazyrtare.md index e94f96588..a68e47e99 100644 --- a/docs/customising/states_informatazyrtare.md +++ b/docs/customising/states_informatazyrtare.md @@ -13,7 +13,7 @@ title: States of requests (InformataZyrtare) </p> The request states are defined in the Alaveteli code, and we recommend you use -them (provided they match the <a href="{{ site.baseurl }}docs/glossary/#foi" +them (provided they match the <a href="{{ page.baseurl }}/docs/glossary/#foi" class="glossary__link">FOI law</a> in your own jurisdiction). ## InformataZyrtare.org (Kosovo) example @@ -29,7 +29,7 @@ facilitates this by allowing you to customise the states that are used. This example is to show clearly that you can use different states depending on your local requirements, and how that might look. See [Customising the request -states]({{ site.baseurl }}docs/customising/themes/) for details on how to do this. +states]({{ page.baseurl }}/docs/customising/themes/) for details on how to do this. ### States used by InformataZyrtare but not WDTK @@ -39,13 +39,13 @@ states]({{ site.baseurl }}docs/customising/themes/) for details on how to do thi ### States used by WDTK but not InformataZyrtare - * <a href="{{ site.baseurl }}docs/customising/states/#awaiting_description">awaiting_description</a> - * <a href="{{ site.baseurl }}docs/customising/states/#gone_postal">gone_postal</a> - * <a href="{{ site.baseurl }}docs/customising/states/#internal_review">internal_review</a> - * <a href="{{ site.baseurl }}docs/customising/states/#user_withdrawn">user_withdrawn</a> - * <a href="{{ site.baseurl }}docs/customising/states/#waiting_response_very_overdue">waiting_response_very_overdue</a> + * <a href="{{ page.baseurl }}/docs/customising/states/#awaiting_description">awaiting_description</a> + * <a href="{{ page.baseurl }}/docs/customising/states/#gone_postal">gone_postal</a> + * <a href="{{ page.baseurl }}/docs/customising/states/#internal_review">internal_review</a> + * <a href="{{ page.baseurl }}/docs/customising/states/#user_withdrawn">user_withdrawn</a> + * <a href="{{ page.baseurl }}/docs/customising/states/#waiting_response_very_overdue">waiting_response_very_overdue</a> -For more details, see all the [states used by WhatDoTheyKnow]({{site.baseurl}}docs/customising/states/) for details. +For more details, see all the [states used by WhatDoTheyKnow]({{ page.baseurl }}/docs/customising/states/) for details. --- @@ -54,7 +54,7 @@ For more details, see all the [states used by WhatDoTheyKnow]({{site.baseurl}}do ### Details of InformataZytare states -The states which aren't represented on [WDTK's states]({{ site.baseurl }}docs/customising/states/) are described +The states which aren't represented on [WDTK's states]({{ page.baseurl }}/docs/customising/states/) are described in a little more detail here: <ul class="definitions"> diff --git a/docs/customising/themes.md b/docs/customising/themes.md index a2b498084..152277b3f 100644 --- a/docs/customising/themes.md +++ b/docs/customising/themes.md @@ -13,7 +13,7 @@ title: Themes </p> When you customise your Alaveteli site, there is a lot you can change just -by editing the [config settings]({{ site.baseurl }}docs/customising/config/). +by editing the [config settings]({{ page.baseurl }}/docs/customising/config/). But if you want to change the way the site looks, or add more specific behaviour, you'll need to make a **theme**. @@ -46,23 +46,23 @@ about this, [ask for help](/community/)! We use -<a href="{{ site.baseurl }}docs/glossary/#git" class="glossary__link">git</a> +<a href="{{ page.baseurl }}/docs/glossary/#git" class="glossary__link">git</a> to manage Alaveteli's source code, and Alaveteli expects your theme to be in a git repository of its own. Although you *can* start customising your site on your -<a href="{{ site.baseurl }}docs/glossary/#development" class="glossary__link">development server</a> +<a href="{{ page.baseurl }}/docs/glossary/#development" class="glossary__link">development server</a> by playing with the `alavetelitheme` theme that Alaveteli ships with, we recommend you make it into your own repo as soon as you can. If you're seriously customising — and certainly before you can deploy to a -<a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production server</a> — +<a href="{{ page.baseurl }}/docs/glossary/#production" class="glossary__link">production server</a> — you must do this. Make sure you choose a unique name for your theme (and hence its repo). If your site is `abcexample.com`, we suggest you call your theme something like `abcexample-theme`. Alaveteli's `themes:install` rake task, which installs themes, works by getting the git repo from the URL specified in the config setting -[`THEME_URLS`]({{ site.baseurl }}docs/customising/config/#theme_urls). This is +[`THEME_URLS`]({{ page.baseurl }}/docs/customising/config/#theme_urls). This is why your theme must be in its own git repo. One way to create your own theme is to fork the `alavetelitheme` theme from @@ -75,7 +75,7 @@ you can duplicate `alivetelitheme` (in `lib/themes/`) and change its name. Here's an example of a complex theme in action: see the theme repo at <a href="https://github.com/mysociety/whatdotheyknow-theme">https://github.com/mysociety/whatdotheyknow-theme</a>. This is the theme for UK's Alaveteli instance - <a href="{{ site.baseurl}}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>. + <a href="{{ page.baseurl }}/docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>. You can see it <a href="https://www.whatdotheyknow.com">deployed on the WhatDoTheyKnow website</a>. This happens because the WhatDoTheyKnow server has this setting in <code>config/general.yml</code>: @@ -92,7 +92,7 @@ The most common requirement is to brand the site: at a minimum, [add the categories](#adding-your-own-categories-for-authorities) that authorities can appear in (you can see these as groupings on the left-hand side of the [View authorities](https://www.whatdotheyknow.com/body/list/all) page -on <a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>). +on <a href="{{ page.baseurl }}/docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>). You may also want to [tweak the different states](#customising-the-request-states) that a request can go through. @@ -116,15 +116,15 @@ We try to encapsulate all site-specific functionality in one of these places: * **site configuration**<br> - use the [config settings]({{ site.baseurl }}docs/customising/config/) + use the [config settings]({{ page.baseurl }}/docs/customising/config/) for example, the name of your site, the available languages, and so on. You change these by editing `config/general.yml`. * **data**<br> for example, the public authorities to whom requests should be addressed, and the tags and categories for grouping them. You control all this through the - <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin - interface</a>: see the [admin manual]({{ site.baseurl }}docs/running/admin_manual). + <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin + interface</a>: see the [admin manual]({{ page.baseurl }}/docs/running/admin_manual). * **a theme**<br> installed in `lib/themes`. The page you're reading now is all about what you can do in a theme. @@ -140,7 +140,7 @@ You can also install the theme by hand, by running: bundle exec rake themes:install This installs whichever theme is specified by the -[`THEME_URLS`]({{ site.baseurl }}docs/customising/config/#theme_urls) +[`THEME_URLS`]({{ page.baseurl }}/docs/customising/config/#theme_urls) setting. The sample theme contains examples for nearly everything you might @@ -149,7 +149,7 @@ use that as the basis for your own theme. <div class="attention-box info"> The - <code><a href="{{ site.baseurl }}docs/customising/config/#theme_urls">THEME_URLS</a></code> + <code><a href="{{ page.baseurl }}/docs/customising/config/#theme_urls">THEME_URLS</a></code> setting allows you to specifiy more than one theme — but normally you only need one. </div> @@ -180,7 +180,7 @@ own, for your own users. The core templates define the layout and user interface of an Alaveteli site. They are in `app/views/` and use -<a href="{{ site.baseurl }}" class="glossary__link">Rails</a>' +<a href="{{ page.baseurl }}/" class="glossary__link">Rails</a>' ERB syntax. For example, the template for the home page lives at `app/views/general/frontpage.html.erb`, and the template for the "about us" page is at `app/views/help/about.html.erb`. @@ -198,7 +198,7 @@ then that will appear instead of the core "about us" file. Alaveteli uses Rails' [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) to convert and compress stylesheets written in -<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary__link">Sass</a> +<a href="{{ page.baseurl }}/docs/glossary/#sass" class="glossary__link">Sass</a> into minified concatenated CSS. Assets are stored in core Alaveteli under `app/assets` -- in `fonts`, `images`, `javascripts` and `stylesheets`. The default theme has corresponding asset directories in `alavetelitheme/assets` @@ -210,7 +210,7 @@ site instead of the logo from `app/assets/images/logo.png`. ### Changing the colour scheme Alaveteli uses a set of basic -<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary__link">Sass</a> +<a href="{{ page.baseurl }}/docs/glossary/#sass" class="glossary__link">Sass</a> modules to define the layout for the site on different device sizes, and some basic styling. These modules are in `app/assets/stylesheets/responsive`. The colours and fonts are added in the theme -- `alavetelitheme` defines them in @@ -238,26 +238,26 @@ You can load extra stylesheets and javascript files by adding them to ## Adding your own categories for authorities You should add -<a href="{{ site.baseurl }}docs/glossary/#category" class="glossary__link">categories</a> +<a href="{{ page.baseurl }}/docs/glossary/#category" class="glossary__link">categories</a> for the authorities on your site -- Alaveteli will display the authorities grouped by categories if you have set any up. Alaveteli uses -<a href="{{ site.baseurl }}docs/glossary/#tag" class="glossary__link">tags</a> +<a href="{{ page.baseurl }}/docs/glossary/#tag" class="glossary__link">tags</a> to assign authorities to the right categories, but you should add tags anyway because they are also used by the site's search facility. Together, categories and tags help your users find the right authority for their request. You can set all this up using the -<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>. -See [more about categories and tags]({{ site.baseurl }}docs/running/categories_and_tags/) +<a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>. +See [more about categories and tags]({{ page.baseurl }}/docs/running/categories_and_tags/) for details. ## Customising the request states As mentioned above, if you can possibly live with the -[default Alaveteli request statuses]({{ site.baseurl }}docs/customising/states/), +[default Alaveteli request statuses]({{ page.baseurl }}/docs/customising/states/), it would be good to do so. You can set how many days must pass before a request is considered "overdue" in the main site config file — -see [`REPLY_LATE_AFTER_DAYS`]({{ site.baseurl }}docs/customising/config/#reply_late_after_days). +see [`REPLY_LATE_AFTER_DAYS`]({{ page.baseurl }}/docs/customising/config/#reply_late_after_days). If you can't live with the states as they are, there's a very basic way to add to them (we're working on this, so it will be improved over time). Currently, @@ -313,24 +313,24 @@ The important pages to customise and translate are listed here. We note where Al * [contact](https://github.com/mysociety/alaveteli/blob/master/app/views/help/contact.html.erb): how to get in touch -* [credits](https://github.com/mysociety/alaveteli/blob/master/app/views/help/credits.html.erb): who is involved in the site. Importantly, includes [a section](https://github.com/mysociety/alaveteli/blob/master/app/views/help/credits.html.erb#L71) on how users can help the project. Users are referred to this section if they categorise all the requests in the [categorisation game]({{ site.baseurl }}docs/glossary/#categorisation-game). +* [credits](https://github.com/mysociety/alaveteli/blob/master/app/views/help/credits.html.erb): who is involved in the site. Importantly, includes [a section](https://github.com/mysociety/alaveteli/blob/master/app/views/help/credits.html.erb#L71) on how users can help the project. Users are referred to this section if they categorise all the requests in the [categorisation game]({{ page.baseurl }}/docs/glossary/#categorisation-game). * [officers](https://github.com/mysociety/alaveteli/blob/master/app/views/help/officers.html.erb): information for the officers who deal with FOI at authorities. They get a link to this page in emails that the site sends them. -* [privacy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/privacy.html.erb): privacy policy, plus information making it clear that requests are going to appear on the internet. Let users know if they are allowed to use pseudonyms in your jurisdiction. Users are referred to the [section on this page](https://github.com/mysociety/alaveteli/blob/master/app/views/help/privacy.html.erb#L114) about what to do if the authority says they only have a paper copy of the information requested if the user classifies their request as ['gone postal']({{ site.baseurl }}docs/customising/states/#gone_postal). +* [privacy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/privacy.html.erb): privacy policy, plus information making it clear that requests are going to appear on the internet. Let users know if they are allowed to use pseudonyms in your jurisdiction. Users are referred to the [section on this page](https://github.com/mysociety/alaveteli/blob/master/app/views/help/privacy.html.erb#L114) about what to do if the authority says they only have a paper copy of the information requested if the user classifies their request as ['gone postal']({{ page.baseurl }}/docs/customising/states/#gone_postal). * [requesting](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.html.erb): the main help page about making requests. How it works, how to decide who to write to, what they can expect in terms of responses, how to make appeals, etc. Users are referred to the [section on how quickly a response to their request should arrive](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.html.erb#L125) when their request is overdue for a response. They are referred to the [section on what to do if the Alaveteli site isn't showing the authority they want to request information](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.html.erb#L30) from the page that allows them to list and search authorities. * [unhappy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.html.erb): users are taken to this page after a request that has been somehow unsuccessful (e.g. the request has been refused, or the authority is insisting on a postal request). The page should encourage them to keep going, e.g. by starting a new request or addressing it to a different body. In particular users are referred to the [section on using other means](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.html.erb#L83) to get their question answered. If the user has requested an internal review of their request, they are referred to [the section on this page](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.html.erb#L28) that describes the law relating to how long a review should take. -* [why email](https://github.com/mysociety/alaveteli/blob/master/app/views/help/_why_they_should_reply_by_email.html.erb): a snippet of information that explains why users should insist on replies by email. This is displayed next to requests that have ["gone postal"]({{ site.baseurl }}docs/customising/states/#gone_postal) - where the authority has asked for the user's physical address so that they can reply with a paper response. +* [why email](https://github.com/mysociety/alaveteli/blob/master/app/views/help/_why_they_should_reply_by_email.html.erb): a snippet of information that explains why users should insist on replies by email. This is displayed next to requests that have ["gone postal"]({{ page.baseurl }}/docs/customising/states/#gone_postal) - where the authority has asked for the user's physical address so that they can reply with a paper response. * [sidebar](https://github.com/mysociety/alaveteli/blob/master/app/views/help/_sidebar.html.erb): a menu for the help pages with a link to each one. You should customise this so that it includes any extra help pages you add, and doesn't include any you remove. You can add your own help pages to your site by replacing the default pages in your theme with your own versions, using a locale suffix for each page to indicate what language the page is written in. No locale -suffix is needed for pages written for the [default locale]({{ site.baseurl }}docs/customising/config/#default_locale) for the site. +suffix is needed for pages written for the [default locale]({{ page.baseurl }}/docs/customising/config/#default_locale) for the site. For example, [alavetelitheme contains help pages](https://github.com/mysociety/alavetelitheme/tree/master/lib/views/help) for the default 'en' locale and an example Spanish 'about' page. If no @@ -355,7 +355,7 @@ level, see `alavetelitheme/lib/controller_patches.rb` and ## Quickly switching between themes On your -<a href="{{ site.baseurl }}docs/glossary/#development" class="glossary__link">development server</a>, +<a href="{{ page.baseurl }}/docs/glossary/#development" class="glossary__link">development server</a>, you can use [`script/switch-theme.rb`](https://github.com/mysociety/alaveteli/blob/master/script/switch-theme.rb) to set the current theme if you are working with multiple themes. This can be diff --git a/docs/customising/translation.md b/docs/customising/translation.md index bc0b52b6e..28d5c76e7 100644 --- a/docs/customising/translation.md +++ b/docs/customising/translation.md @@ -17,7 +17,7 @@ title: Translation Alaveteli ships ready to run in a number of different languages. If Alaveteli has already been translated into the language (or languages) you need, you just need to configure it -- see -[`AVAILABLE_LOCALES`]({{ site.baseurl }}docs/customising/config/#available_locales). +[`AVAILABLE_LOCALES`]({{ page.baseurl }}/docs/customising/config/#available_locales). [Look in the `locale/` directory](https://github.com/mysociety/alaveteli/tree/master/locale) to see what translations are already available. Some are complete @@ -40,7 +40,7 @@ There are two reasons the translations may need more work before you can use the current translation and what state it's in. Translators are members of the Alaveteli -[community]({{site.baseurl}}community/), and often work separately from the +[community]({{ page.baseurl }}/community/), and often work separately from the developers. This means translations can lag a little behind the code. However, our release process includes a "translation freeze", which gives the translators a chance to catch up -- read the rest of this page for details. @@ -48,7 +48,7 @@ translators a chance to catch up -- read the rest of this page for details. ## Alaveteli's translations You don't need to be a programmer to translate Alaveteli -- we use an external -website called <a href="{{ site.baseurl }}docs/glossary/#transifex" class="glossary__link">Transifex</a> to help manage translations. This makes it easy for +website called <a href="{{ page.baseurl }}/docs/glossary/#transifex" class="glossary__link">Transifex</a> to help manage translations. This makes it easy for translators to get to work, but it does mean you (or your technical team) need to do a little extra work to get those translations back into Alaveteli when they are ready. @@ -59,9 +59,9 @@ The Transifex project is at fairly easy-to-use interface for contributing translations. Alaveteli localises strings using GNU gettext and -<a href="{{site.baseurl}}docs/glossary/#po" class="glossary__link"><code>.pot</code> & <code>.po</code> files</a>. +<a href="{{ page.baseurl }}/docs/glossary/#po" class="glossary__link"><code>.pot</code> & <code>.po</code> files</a>. If you're a developer, you should read -[internationalising Alaveteli]({{ site.baseurl }}docs/developers/i18n/). +[internationalising Alaveteli]({{ page.baseurl }}/docs/developers/i18n/). ## What a translator needs to do @@ -79,10 +79,10 @@ use some code to mark sentences or words ("strings") that they think will need to be translated. When the Alaveteli -<a href="{{site.baseurl}}docs/glossary/#release" class="glossary__link">release manager</a> +<a href="{{ page.baseurl }}/docs/glossary/#release" class="glossary__link">release manager</a> is planning a release, they will upload a template containing all the strings to be translated (called a -<a href="{{site.baseurl}}docs/glossary/#po" class="glossary__link"><code>.pot</code> file</a>) +<a href="{{ page.baseurl }}/docs/glossary/#po" class="glossary__link"><code>.pot</code> file</a>) to Transifex. This causes your own translations in Transifex to be updated with the latest strings. @@ -156,7 +156,7 @@ translate the text that comes *after* the `|`. ## How the translations get into Alaveteli In order to get the translated strings from Transifex into Alaveteli, follow -the instructions in these [deployment notes]({{ site.baseurl }}docs/developers/i18n/#deployment-notes). +the instructions in these [deployment notes]({{ page.baseurl }}/docs/developers/i18n/#deployment-notes). This will be the job of the technical people on your team (or even mySociety's release manager). If translators aren't technical, they can use Transifex without needing to worry about this. @@ -166,7 +166,7 @@ use Transifex without needing to worry about this. As the help pages for Alaveteli contain lots of text, they're translated outside Transifex, by translating each whole help page and replacing it in the theme that Alaveteli is using, so that it overrides the default -page. See the [guide to Alaveteli's themes]({{ site.baseurl }}docs/customising/themes/#customising-the-help-pages) for more +page. See the [guide to Alaveteli's themes]({{ page.baseurl }}/docs/customising/themes/#customising-the-help-pages) for more information on this. ## Developers and internationalisation @@ -174,7 +174,7 @@ information on this. If you're writing new code for Alaveteli, then you're a developer, and you need to understand how to make any text you add easy for translators to work with -- see the page about -[internationalising Alaveteli]({{site.baseurl}}docs/developers/i18n/). +[internationalising Alaveteli]({{ page.baseurl }}/docs/developers/i18n/). If you are a developer or translator actively working on internationalising Alaveteli code, you should talk to us to find out when the next release is due, diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md index fb7f2930b..c10ebeab8 100644 --- a/docs/developers/i18n.md +++ b/docs/developers/i18n.md @@ -7,11 +7,11 @@ title: Internationalisation (for devs) <p class="lead"> This page describes some technical aspects of - <a href="{{ site.baseurl }}docs/glossary/#i18n" class="glossary__link">internationalising</a> + <a href="{{ page.baseurl }}/docs/glossary/#i18n" class="glossary__link">internationalising</a> the Alaveteli code. It's mostly aimed at devs who are working on the codebase — if you just want to translate Alaveteli into your own language, see - <a href="{{ site.baseurl }}docs/customising/translation">translating Alaveteli</a> + <a href="{{ page.baseurl }}/docs/customising/translation">translating Alaveteli</a> instead. </p> @@ -19,9 +19,9 @@ title: Internationalisation (for devs) Deployed translations for the project live in ``locale/``. -We encourage translations to be done on <a href="{{ site.baseurl }}docs/glossary/#transifex" class="glossary__link">Transifex</a> +We encourage translations to be done on <a href="{{ page.baseurl }}/docs/glossary/#transifex" class="glossary__link">Transifex</a> because translators can work through its web interface rather than needing to edit the -<a href="{{ site.baseurl }}docs/glossary/#po" class="glossary__link">`.po` and `.pot` files</a> +<a href="{{ page.baseurl }}/docs/glossary/#po" class="glossary__link">`.po` and `.pot` files</a> directly. Ultimately, Transifex just captures translators' work and turns it into the files that Alaveteli needs (using gettext). @@ -31,7 +31,7 @@ For example, to deploy English and Spanish translations at once: * Ensure their `.po` files are at ```locale/en/app.po``` and ```locale/es/app.po``` (for example, by downloading them from Transifex) - * Set <code><a href="{{ site.baseurl }}docs/customising/config/#available_locales">AVAILABLE_LOCALES</a></code> + * Set <code><a href="{{ page.baseurl }}/docs/customising/config/#available_locales">AVAILABLE_LOCALES</a></code> to <code>en es</code> ### What to do if you don't have complete translations for an older release of Alaveteli @@ -56,7 +56,7 @@ You need to do this if you've added any new strings to the code that need translations (or if you change an existing one). To update the -<a href="{{ site.baseurl }}docs/glossary/#po" class="glossary__link">`.po` or `.pot` files</a> +<a href="{{ page.baseurl }}/docs/glossary/#po" class="glossary__link">`.po` or `.pot` files</a> for each language, run: bundle exec rake gettext:store_model_attributes @@ -69,7 +69,7 @@ If `gettext:find` only creates the file `locale/im-config.pot` then you need to unset the `TEXTDOMAIN` environment variable and try again. For more details about the translations, see the page about -[translating Alaveteli]({{ site.baseurl }}docs/customising/translation/). +[translating Alaveteli]({{ page.baseurl }}/docs/customising/translation/). ## Technical implementation details @@ -173,5 +173,5 @@ The release manager will enforce a translation freeze just before a new release is cut. During such time, you must not introduce new strings to the code if your work is due for inclusion in this release. This is necessary to allow translators time to complete and check their translations against all the known -strings. See more about [translating Alaveteli]({{ site.baseurl }}docs/customising/translation/). +strings. See more about [translating Alaveteli]({{ page.baseurl }}/docs/customising/translation/). diff --git a/docs/developers/index.md b/docs/developers/index.md index f1167a22b..bcf74be16 100644 --- a/docs/developers/index.md +++ b/docs/developers/index.md @@ -16,10 +16,10 @@ title: For developers reasons, we recommend the use of [Varnish](https://www.varnish-cache.org). * To help you understand what the code is doing, read this [high-level - overview]({{ site.baseurl }}docs/developers/overview/), which includes a diagram of + overview]({{ page.baseurl }}/docs/developers/overview/), which includes a diagram of the models and how they are related. -* See the [API documentation]({{ site.baseurl }}docs/developers/api/) for how to get +* See the [API documentation]({{ page.baseurl }}/docs/developers/api/) for how to get data into or out of Alaveteli. * If you need to change or add strings in the interface, see our [guidelines @@ -40,23 +40,23 @@ title: For developers * Installing the software is a little involved, though it's getting easier. If you stick to Debian or Ubuntu, it should be possible to get a running version within a few hours. If you've got your own server, run the - [installation script]({{ site.baseurl }}docs/installing/script/), or follow the + [installation script]({{ page.baseurl }}/docs/installing/script/), or follow the instructions for a - [manual installation]({{ site.baseurl }}docs/installing/manual_install/). - Alternatively, there's an [Alaveteli EC2 AMI]({{ site.baseurl }}docs/installing/ami/) + [manual installation]({{ page.baseurl }}/docs/installing/manual_install/). + Alternatively, there's an [Alaveteli EC2 AMI]({{ page.baseurl }}/docs/installing/ami/) that might help you get up and running quickly. - [Get in touch]({{ site.baseurl }}community/) on the project mailing list or IRC + [Get in touch]({{ page.baseurl }}/community/) on the project mailing list or IRC for help. * A standard initial step for customising your deployment is [writing a - theme]({{ site.baseurl }}docs/customising/themes/). **If you only read one thing, + theme]({{ page.baseurl }}/docs/customising/themes/). **If you only read one thing, it should be this!** * Like many Ruby on Rails sites, the software is not hugely performant (see [these notes about performance issues](https://github.com/mysociety/alaveteli/wiki/Performance-issues) gathered over time with WhatDoTheyKnow). The site will run on a server with 512MB RAM but at least 2GB is recommended. Deployment behind [Varnish](https://www.varnish-cache.org) is also fairly essential. See - [production server best practices]({{site.baseurl}}docs/running/server/) for more. + [production server best practices]({{ page.baseurl }}/docs/running/server/) for more. * There's a number of [proposals for enhancements](https://github.com/mysociety/alaveteli/wiki/Proposals-for-enhancements), such as more user-focused features, but see also... @@ -76,7 +76,7 @@ title: For developers used in the past](https://www.mysociety.org/2009/09/17/whatdotheyknow-growing-pains-and-ruby-memory-leaks/) might be useful. -* If you're coding on a mac, see these [MacOS X installation notes]({{ site.baseurl }}docs/installing/macos/). <!-- [[OS X Quickstart]] --> +* If you're coding on a mac, see these [MacOS X installation notes]({{ page.baseurl }}/docs/installing/macos/). <!-- [[OS X Quickstart]] --> * We try to adhere to similar good practice across all our projects: see [mysociety.github.io](http://mysociety.github.io/) for things like our diff --git a/docs/getting_started.md b/docs/getting_started.md index 3ea67c818..bd8788ff3 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -114,11 +114,11 @@ help with this. The minimum spec for running a low traffic website is latest Debian Wheezy (7) or Squeeze (6) 64-bit or Ubuntu precise (12.04) as the operating system. Rackspace offer suitable cloud servers, which start out at around $25 / month. Then your tech person should follow the -[installation documentation]({{ site.baseurl }}docs/installing/). +[installation documentation]({{ page.baseurl }}/docs/installing/). Alternatively, you could use Amazon Web Services. This has the added advantage that you can use our preconfigured [Alaveteli EC2 -AMI]({{ site.baseurl }}docs/installing/ami/) to get you +AMI]({{ page.baseurl }}/docs/installing/ami/) to get you started almost instantly. However, it's more expensive than Rackspace, especially if you want more RAM. @@ -189,7 +189,7 @@ custom homepage, different fonts, etc; however, the more you customise the site, the harder it is to upgrade in the future; and you'll need a developer and/or designer to help do these customisations. We call the custom set of colours, fonts, logos etc a "theme"; there are some notes for developers about -[writing a theme]({{ site.baseurl }}docs/customising/themes/). You +[writing a theme]({{ page.baseurl }}/docs/customising/themes/). You might spend anywhere between 1 and 15 days on this. ### Legislative differences @@ -216,7 +216,7 @@ often less. But complicated workflows might take a bit longer. The default help pages in Alaveteli are taken from WhatDoTheyKnow, and are therefore relevant only to the UK. You should take these pages as inspiration, -but review their content with a view to your jurisdiction. See [the documentation on Alaveteli's themes]({{ site.baseurl }}docs/customising/themes/#customising-the-help-pages) for details +but review their content with a view to your jurisdiction. See [the documentation on Alaveteli's themes]({{ page.baseurl }}/docs/customising/themes/#customising-the-help-pages) for details on which pages are important, and what content they need to have. The help pages contain some HTML. Your tech person should be able to advise on @@ -229,7 +229,7 @@ that you'll be sending out in response to common user queries and administrative tasks -- for example, an email that you send to IT departments asking them to whitelist emails from your Alaveteli website (if your emails are being marked as spam). See the -[Administrator's Manual]({{ site.baseurl }}docs/running/admin_manual/) for details +[Administrator's Manual]({{ page.baseurl }}/docs/running/admin_manual/) for details on some of the common administrative tasks. There is a list of the standard emails used by WhatDoTheyKnow on the [FOI Wiki](http://foiwiki.com/foiwiki/index.php/Common_WhatDoTheyKnow_support_responses). @@ -276,7 +276,7 @@ spreadsheet. The help pages need to have one copy saved for each language; your tech person will put them in the right place. The web interface translations are managed and collaborated via a website -called <a href="{{ site.baseurl }}docs/glossary/#transifex" class="glossary__link">Transifex</a>. This website allows teams of translators to collaborate in +called <a href="{{ page.baseurl }}/docs/glossary/#transifex" class="glossary__link">Transifex</a>. This website allows teams of translators to collaborate in one place, using a fairly easy interface. The Alaveteli page on Transifex is at @@ -303,7 +303,7 @@ review the untranslated strings. ## Step five: Test drive the site For launch, the tech person should review the [Production Server Best -Practices]({{ site.baseurl }}docs/running/server/). +Practices]({{ page.baseurl }}/docs/running/server/). A low-key launch, where you tell just a few trusted people about the site, is a very good idea. You can then track how things work, and gauge the responses of diff --git a/docs/glossary.md b/docs/glossary.md index d0e03b41d..94b29648c 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -66,14 +66,14 @@ Definitions </dt> <dd> The <strong>admin interface</strong> allows users who have - <a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">super</a> + <a href="{{ page.baseurl }}/docs/glossary/#super" class="glossary__link">super</a> administrator privilege to manage some aspects of how your Alaveteli site runs. <div class="more-info"> <p>More information:</p> <ul> <li> - You can access your installation's <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a> + You can access your installation's <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a> at <code>/admin</code>. </li> <li> @@ -83,13 +83,12 @@ Definitions </li> <li> On a newly-installed Alaveteli system, you can grant yourself - admin privilege by using the - <a href="{{ site.baseurl }}docs/glossary/#emergency" class="glossary__link">emergency + <a href="{{ page.baseurl }}/docs/glossary/#emergency" class="glossary__link">emergency user</a>. </li> <li> For lots more about running an Alaveteli site, see the - <a href="{{ site.baseurl }}running/admin_manual">adminstrator's guide</a>. + <a href="{{ page.baseurl }}/running/admin_manual">adminstrator's guide</a>. </li> </ul> </div> @@ -193,7 +192,7 @@ Definitions </li> <li> You can organise your authorities using - <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a>. + <a href="{{ page.baseurl }}/docs/running/categories_and_tags/">categories and tags</a>. </li> </ul> </div> @@ -212,12 +211,12 @@ Definitions <ul> <li> Use the config setting - <code><a href="{{site.baseurl}}docs/customising/config/#blackhole_prefix">BLACKHOLE_PREFIX</a></code> + <code><a href="{{ page.baseurl }}/docs/customising/config/#blackhole_prefix">BLACKHOLE_PREFIX</a></code> to specify what this email address looks like. </li> <li> Conversely, see - <code><a href="{{site.baseurl}}docs/customising/config/#contact_email">CONTACT_EMAIL</a></code> + <code><a href="{{ page.baseurl }}/docs/customising/config/#contact_email">CONTACT_EMAIL</a></code> to specify the email address to which users' emails (such as support enquiries) will be delivered. </li> @@ -235,7 +234,7 @@ Definitions <p>More information:</p> <ul> <li> - <a href="{{ site.baseurl }}docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a> + <a href="{{ page.baseurl }}/docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a> </li> <li>The wikipedia page on <a href="http://en.wikipedia.org/wiki/Bounce_message">bounce messages</a> </li> @@ -253,7 +252,7 @@ Definitions <p>More information:</p> <ul> <li> - how to <a href="{{ site.baseurl }}docs/installing/deploy/">deploy Alaveteli</a> (and why it's + how to <a href="{{ page.baseurl }}/docs/installing/deploy/">deploy Alaveteli</a> (and why it's a good idea) </li> <li> @@ -282,7 +281,7 @@ Definitions authorities with specific categories. </p> More about - <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a> + <a href="{{ page.baseurl }}/docs/running/categories_and_tags/">categories and tags</a> </dd> <dt> <a name="categorisation-game">categorisation game</a> @@ -312,7 +311,7 @@ Definitions <ul> <li> see the - <a href="{{ site.baseurl }}docs/running/admin_manual/">admin manual</a> + <a href="{{ page.baseurl }}/docs/running/admin_manual/">admin manual</a> for more about censor rules </li> <li> @@ -329,7 +328,7 @@ Definitions </dt> <dd> A <strong>dev server</strong> is one that is running your Alaveteli site - so you can <a href="{{ site.baseurl }}docs/customising/">customise it</a>, experiment + so you can <a href="{{ page.baseurl }}/docs/customising/">customise it</a>, experiment with different settings, and test that it does what you expect. This is different from a <a href="#production" class="glossary__link">production server</a>, which is the one your @@ -338,7 +337,7 @@ Definitions which is used for testing code before it goes live. <p> On your dev server, you should set - <code><a href="{{site.baseurl}}docs/customising/config/#staging_site">STAGING_SITE</a></code> + <code><a href="{{ page.baseurl }}/docs/customising/config/#staging_site">STAGING_SITE</a></code> to <code>1</code>. </p> </dd> @@ -357,7 +356,7 @@ Definitions <ul> <li> You can add a disclosure log URL by - <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">updating authority data</a> in the admin. + <a href="{{ page.baseurl }}/docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">updating authority data</a> in the admin. </li> </ul> </div> @@ -380,18 +379,18 @@ Definitions <ul> <li> The username and password are defined by the configuration settings - <code><a href="{{site.baseurl}}docs/customising/config/#admin_username">ADMIN_USERNAME</a></code> + <code><a href="{{ page.baseurl }}/docs/customising/config/#admin_username">ADMIN_USERNAME</a></code> and - <code><a href="{{site.baseurl}}docs/customising/config/#admin_password">ADMIN_PASSWORD</a></code>. + <code><a href="{{ page.baseurl }}/docs/customising/config/#admin_password">ADMIN_PASSWORD</a></code>. </li> <li> For an example of using the emergency user, see - <a href="{{site.baseurl}}docs/installing/next_steps/#create-a-superuser-account-for-yourself">creating + <a href="{{ page.baseurl }}/docs/installing/next_steps/#create-a-superuser-account-for-yourself">creating a superuser account</a>. </li> <li> Disable the emergency user by setting - <code><a href="{{site.baseurl}}docs/customising/config/#disable_emergency_user">DISABLE_EMERGENCY_USER:</a> true</code> + <code><a href="{{ page.baseurl }}/docs/customising/config/#disable_emergency_user">DISABLE_EMERGENCY_USER:</a> true</code> </li> </ul> </div> @@ -441,7 +440,7 @@ Definitions <p>More information:</p> <ul> <li> - See the <a href="{{ site.baseurl }}docs/installing/">installation instructions</a> which will + See the <a href="{{ page.baseurl }}/docs/installing/">installation instructions</a> which will clone the Alaveteli repo. </li> <li> @@ -473,7 +472,7 @@ Definitions <p>More information:</p> <ul> <li> - See more <a href="{{ site.baseurl }}docs/running/holding_pen">about + See more <a href="{{ page.baseurl }}/docs/running/holding_pen">about the holding pen</a>, including why messages end up there, and instructions on what to do with them. </li> @@ -521,12 +520,12 @@ Definitions <p> Often you don't need to worry about the details of how this is done because once you've configured your site's - <code><a href="{{ site.baseurl }}docs/customising/config/#default_locale">DEFAULT_LOCALE</a></code> + <code><a href="{{ page.baseurl }}/docs/customising/config/#default_locale">DEFAULT_LOCALE</a></code> Alaveteli takes care of it for you. But when you do need to work on i18n (for example, if you're customising your site by - <a href="{{ site.baseurl }}docs/customising/translation/">translating</a> it, or - <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">uploading names</a> + <a href="{{ page.baseurl }}/docs/customising/translation/">translating</a> it, or + <a href="{{ page.baseurl }}/docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">uploading names</a> of the public bodies in more than one language) at the very least you may need to know the language codes you're site is using. </p> @@ -534,7 +533,7 @@ Definitions <p>More information:</p> <ul> <li> - More about <a href="{{ site.baseurl }}docs/developers/i18n/">internationalising Alaveteli</a> + More about <a href="{{ page.baseurl }}/docs/developers/i18n/">internationalising Alaveteli</a> </li> <li> See mySociety's @@ -563,7 +562,7 @@ Definitions <p>More information:</p> <ul> <li> - see these instructions for <a href="{{ site.baseurl }}docs/installing/email/">configuring your MTA</a> + see these instructions for <a href="{{ page.baseurl }}/docs/installing/email/">configuring your MTA</a> (examples are for exim4 and postfix, two of the most common) </li> </ul> @@ -584,7 +583,7 @@ Definitions <li> use the <code>agent_enabled:</code> setting in the the <code>newrelic.yml</code> config file to enable the New Relic analytics. - See the <a href="{{ site.baseurl }}docs/installing/manual_install/">manual installation</a> instructions. + See the <a href="{{ page.baseurl }}/docs/installing/manual_install/">manual installation</a> instructions. </li> <li> see also the New Relic Ruby Agent <a href="https://github.com/newrelic/rpm">github repo</a> and @@ -613,11 +612,11 @@ Definitions <p>More information:</p> <ul> <li> - See <a href="{{ site.baseurl }}docs/customising/translation/">translating + See <a href="{{ page.baseurl }}/docs/customising/translation/">translating Alaveteli</a> for an overview from a translator's point of view. </li> <li> - See <a href="{{ site.baseurl }}docs/developers/i18n/">Internationalising + See <a href="{{ page.baseurl }}/docs/developers/i18n/">Internationalising Alaveteli</a> for more technical details. </li> <li> @@ -649,7 +648,7 @@ Definitions example, caching is enabled, and debugging switched off. <a href="#rails" class="glossary__link">Rails</a> has a "production mode" which does this for you: set - <code><a href="{{site.baseurl}}docs/customising/config/#staging_site">STAGING_SITE</a></code> + <code><a href="{{ page.baseurl }}/docs/customising/config/#staging_site">STAGING_SITE</a></code> to <code>0</code>. Note that if you <em>change</em> this setting after you've deployed, the <code>rails_env.rb</code> file that enables Rails's production mode won't be created until you run <code>rails-post-deploy</code>. @@ -660,7 +659,7 @@ Definitions <p> You should never need to edit code directly on your production server. We strongly recommend you use Alaveteli's - <a href="{{ site.baseurl }}docs/installing/deploy/">deployment mechanism</a> + <a href="{{ page.baseurl }}/docs/installing/deploy/">deployment mechanism</a> (using Capistrano) to make changes to your production site. </p> </dd> @@ -695,7 +694,7 @@ Definitions <ul> <li> You can add a publication scheme URL by - <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">updating authority data</a> in the admin. + <a href="{{ page.baseurl }}/docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">updating authority data</a> in the admin. </li> </ul> </div> @@ -716,9 +715,9 @@ Definitions <ul> <li> use the config settings - <code><a href="{{site.baseurl}}docs/customising/config/#recaptcha_public_key">RECAPTCHA_PUBLIC_KEY</a></code> + <code><a href="{{ page.baseurl }}/docs/customising/config/#recaptcha_public_key">RECAPTCHA_PUBLIC_KEY</a></code> and - <code><a href="{{site.baseurl}}docs/customising/config/#recaptcha_private_key">RECAPTCHA_PRIVATE_KEY</a></code> + <code><a href="{{ page.baseurl }}/docs/customising/config/#recaptcha_private_key">RECAPTCHA_PRIVATE_KEY</a></code> to set this up. </li> <li> @@ -747,7 +746,7 @@ Definitions <ul> <li> see the - <a href="{{ site.baseurl }}docs/running/admin_manual/">admin manual</a> + <a href="{{ page.baseurl }}/docs/running/admin_manual/">admin manual</a> for more about how and when you may need to redact information </li> <li> @@ -822,11 +821,11 @@ Definitions </li> <li> We try to coordinate releases with any active translation work too. - See <a href="{{ site.baseurl }}docs/customising/translation/">translating + See <a href="{{ page.baseurl }}/docs/customising/translation/">translating Alaveteli</a> for more information. </li> <li> - We encourage you use the <a href="{{site.baseurl}}docs/installing/deploy/">deployment + We encourage you use the <a href="{{ page.baseurl }}/docs/installing/deploy/">deployment mechanism</a>, which makes it easier to keep your production server up-to-date. </li> </ul> @@ -868,7 +867,7 @@ Definitions <a href="http://rubyonrails.org/">Ruby on Rails</a> website </li> <li> - Alavateli's <a href="{{ site.baseurl }}docs/developers/directory_structure/">directory structure</a> + Alavateli's <a href="{{ page.baseurl }}/docs/developers/directory_structure/">directory structure</a> is influenced by its use of Ruby on Rails </li> </ul> @@ -894,7 +893,7 @@ Definitions <a href="http://sass-lang.com">Sass website</a> </li> <li> - more about <a href="{{ site.baseurl }}docs/customising/themes/#changing-the-colour-scheme">changing + more about <a href="{{ page.baseurl }}/docs/customising/themes/#changing-the-colour-scheme">changing your colour scheme</a>, which uses Sass </li> </ul> @@ -918,7 +917,7 @@ Definitions <ul> <li> To add addresses to the spam address list , see - <a href="{{ site.baseurl }}docs/running/admin_manual/#rejecting-spam-that-arrives-in-the-holding-pen">Rejecting + <a href="{{ page.baseurl }}/docs/running/admin_manual/#rejecting-spam-that-arrives-in-the-holding-pen">Rejecting spam that arrives in the holding pen</a>. </li> <li> @@ -940,7 +939,7 @@ Definitions site your users visit running with live data. <p> On your staging server, you should set - <code><a href="{{site.baseurl}}docs/customising/config/#staging_site">STAGING_SITE</a></code> + <code><a href="{{ page.baseurl }}/docs/customising/config/#staging_site">STAGING_SITE</a></code> to <code>1</code>. </p> <p> @@ -950,7 +949,7 @@ Definitions <p> You should never need to edit code directly on your production or staging servers. We strongly recommend you use Alaveteli's - <a href="{{ site.baseurl }}docs/installing/deploy/">deployment mechanism</a> + <a href="{{ page.baseurl }}/docs/installing/deploy/">deployment mechanism</a> (using Capistrano) to make changes to these sites. </p> </dd> @@ -972,15 +971,15 @@ Definitions <p>More information:</p> <ul> <li> - <a href="{{ site.baseurl }}docs/customising/states/">example states for WhatDoTheyKnow</a> + <a href="{{ page.baseurl }}/docs/customising/states/">example states for WhatDoTheyKnow</a> (Alaveteli site running in the UK) </li> <li> - for comparison, <a href="{{ site.baseurl }}docs/customising/states_informatazyrtare/">example states for InformataZyrtare</a> + for comparison, <a href="{{ page.baseurl }}/docs/customising/states_informatazyrtare/">example states for InformataZyrtare</a> (Alaveteli site running in Kosovo) </li> <li> - to customise or add your own states, see <a href="{{ site.baseurl }}docs/customising/themes/#customising-the-request-states">Customising the request states</a> + to customise or add your own states, see <a href="{{ page.baseurl }}/docs/customising/themes/#customising-the-request-states">Customising the request states</a> </li> </ul> </div> @@ -992,11 +991,11 @@ Definitions <dd> A <strong>superuser</strong>, or <strong>administrator</strong>, is an Alaveteli user who has been granted the privilege to use all features of the - <a href="{{ site.baseurl }}docs/glossary/#admin" + <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>. <p> The only way to access the admin without being an Alaveteli superuser - is as the <a href="{{ site.baseurl }}docs/glossary/#emergency" + is as the <a href="{{ page.baseurl }}/docs/glossary/#emergency" class="glossary__link">emergency user</a>, which should be disabled in normal operation. </p> @@ -1011,7 +1010,7 @@ Definitions <li> On a newly-installed Alaveteli system, you can grant yourself admin privilege by using the - <a href="{{ site.baseurl }}docs/glossary/#emergency" class="glossary__link">emergency + <a href="{{ page.baseurl }}/docs/glossary/#emergency" class="glossary__link">emergency user</a>. </li> </ul> @@ -1035,7 +1034,7 @@ Definitions <ul> <li> More about - <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a> + <a href="{{ page.baseurl }}/docs/running/categories_and_tags/">categories and tags</a> </li> </ul> </div> @@ -1054,7 +1053,7 @@ Definitions <p>More information:</p> <ul> <li> - <a href="{{ site.baseurl }}docs/customising/themes/">about themes</a> + <a href="{{ page.baseurl }}/docs/customising/themes/">about themes</a> </li> </ul> </div> diff --git a/docs/index.md b/docs/index.md index b8cc66b48..e3c9fe918 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,16 +19,15 @@ You've found the documentation for Alaveteli. * Read [Turbo Transparency](/assets/files/Turbo-Transparency-v1.0.pdf), a paper about how and why to use Alaveteli for Freedom of Information systems -* Read the [Getting Started guide]({{ site.baseurl }}docs/getting_started/) +* Read the [Getting Started guide]({{ page.baseurl }}/docs/getting_started/) **The documentation covers -[installing]({{ site.baseurl }}docs/installing/), -[customising]({{ site.baseurl }}docs/customising/), and -[running]({{ site.baseurl }}docs/running/) your own Alaveteli site.** +[installing]({{ page.baseurl }}/docs/installing/), +[customising]({{ page.baseurl }}/docs/customising/), and +[running]({{ page.baseurl }}/docs/running/) your own Alaveteli site.** If you're making changes to the source code, we have -[documentation for developers]({{ site.baseurl }}docs/developers/) too. +[documentation for developers]({{ page.baseurl }}/docs/developers/) too. If you are an organisation who wants to use Alaveteli in your jurisdiction, or a developer who is interested in collaborating on the software, please -[get in touch]({{ site.baseurl }}community/). - +[get in touch]({{ page.baseurl }}/community/). diff --git a/docs/installing/ami.md b/docs/installing/ami.md index 974c55d0c..44e10d87c 100644 --- a/docs/installing/ami.md +++ b/docs/installing/ami.md @@ -10,28 +10,28 @@ title: Installation from AMI EC2. This is handy if you just want to evaluate Alaveteli, for example. </p> -Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing/). +Note that there are [other ways to install Alaveteli]({{ page.baseurl }}/docs/installing/). ## Installing from our AMI To help you try out Alaveteli, we have created an AMI with a basic installation of Alaveteli, which you can use to create a running server on an Amazon EC2 instance. This creates an instance that runs as a -<a href="{{ site.baseurl }}docs/glossary/#development" class="glossary__link">development site</a>. +<a href="{{ page.baseurl }}/docs/glossary/#development" class="glossary__link">development site</a>. If you want to use this for a -<a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production site</a>, +<a href="{{ page.baseurl }}/docs/glossary/#production" class="glossary__link">production site</a>, you must -[change the configuration]({{ site.baseurl }}docs/customising/config/#staging_site). +[change the configuration]({{ page.baseurl }}/docs/customising/config/#staging_site). <div class="attention-box"> <p> <strong>What's in the AMI?</strong> The AMI gives you exactly the same thing as the - <a href="{{ site.baseurl}}docs/installing/script/">installation script</a> + <a href="{{ page.baseurl }}/docs/installing/script/">installation script</a> does. You get an Alaveteli website powered by Rails running the Thin application server under nginx, using a postgreSQL database. All this running on Amazon's EC2 servers, ready to be - <a href="{{ site.baseurl }}docs/customising/">configured and customised</a>. + <a href="{{ page.baseurl }}/docs/customising/">configured and customised</a>. </p> </div> @@ -132,7 +132,7 @@ When you log into your instance's command line shell, you must do so as the the code is actually owned by (and runs as) the `alaveteli` user. You will need to -[customise the site's configuration]({{ site.baseurl }}docs/customising/config/). +[customise the site's configuration]({{ page.baseurl }}/docs/customising/config/). Do this by logging into your EC2 server and editing the `general.yml` configuration file. @@ -158,4 +158,4 @@ If you have any problems or questions, please ask on the [Alaveteli developer ma ##What next? -Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). +Check out the [next steps]({{ page.baseurl }}/docs/installing/next_steps/). diff --git a/docs/installing/deploy.md b/docs/installing/deploy.md index 74c7a8560..858ef2727 100644 --- a/docs/installing/deploy.md +++ b/docs/installing/deploy.md @@ -9,13 +9,13 @@ title: Deploying Although you can install Alaveteli and just change it when you need it, we recommend you adopt a way of <strong>deploying</strong> it automatically, especially on your - <a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production server</a>. + <a href="{{ page.baseurl }}/docs/glossary/#production" class="glossary__link">production server</a>. Alaveteli provides a deployment mechanism using Capistrano. </p> ## Why deploy? -Although you can [install Alaveteli]({{ site.baseurl }}docs/installing/) in a number +Although you can [install Alaveteli]({{ page.baseurl }}/docs/installing/) in a number of ways, once you're running, sooner or later you'll need to make changes to the site. A common example is updating your site when we issue a new release. @@ -28,13 +28,13 @@ changes or copying files by hand, so your site will be down for the shortest possible time. We **strongly recommend** you use the deployment mechanism for your -<a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production server</a> +<a href="{{ page.baseurl }}/docs/glossary/#production" class="glossary__link">production server</a> and, if you're running one, your -<a href="{{ site.baseurl }}docs/glossary/#staging" class="glossary__link">staging server</a> too. +<a href="{{ page.baseurl }}/docs/glossary/#staging" class="glossary__link">staging server</a> too. ## Capistrano -<a href="{{site.baseurl}}docs/glossary/#capistrano" class="glossary__link">Capistrano</a> +<a href="{{ page.baseurl }}/docs/glossary/#capistrano" class="glossary__link">Capistrano</a> is included as part of Alaveteli as a standard deployment system. The basic principle of Capistrano is that you execute `cap [do-something]` @@ -68,7 +68,7 @@ and thereafter you'll be able to deploy very easily (see [usage, below](#usage)) First, on the server: -* [install Alaveteli]({{ site.baseurl }}docs/installing/) +* [install Alaveteli]({{ page.baseurl }}/docs/installing/) * give the Unix user that runs Alaveteli the ability to ssh to your server. Either give them a password or, preferably, set up ssh keys for them so they can ssh from your local machine to the server: * to give them a password (if they don't already have one) - `sudo passwd [UNIX-USER]`. Store this password securely on your local machine e.g in a password manager * to set up ssh keys for them, follow the instructions in the [capistrano documentation](http://capistranorb.com/documentation/getting-started/authentication-and-authorisation/). There's no need to set up ssh keys to the git repository as it is public. @@ -131,8 +131,8 @@ Now, back on your local machine: * make sure you're still in the Alaveteli repo (if not, `cd` back into it) * run `cap -S stage=staging deploy:update_code` to get a code checkout on the server. * create a deployment directory on the server by running *one* of these commands: - * `cap deploy` if you're deploying a <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary__link">staging site</a>, or... - * `cap -S stage=production deploy` for <a href="{{site.baseurl}}docs/glossary/#production" class="glossary__link">production</a> + * `cap deploy` if you're deploying a <a href="{{ page.baseurl }}/docs/glossary/#staging" class="glossary__link">staging site</a>, or... + * `cap -S stage=production deploy` for <a href="{{ page.baseurl }}/docs/glossary/#production" class="glossary__link">production</a> Back on the server: @@ -151,7 +151,7 @@ Back on the server: If you're using Exim as your MTA, edit `etc/exim4/conf.d/04_alaveteli_options` to update the `ALAVETELI_HOME` variable to the new Alaveteli path. Restart the MTA after you've made these changes. -* You will also need to update the path to Alaveteli in your [init scripts]({{site.baseurl}}docs/installing/manual_install/#cron-jobs-and-init-scripts). +* You will also need to update the path to Alaveteli in your [init scripts]({{ page.baseurl }}/docs/installing/manual_install/#cron-jobs-and-init-scripts). You should have a script for running the alert tracks (`/etc/init.d/foi-alert-tracks`), and possibly scripts for purging the varnish cache (`/etc/init.d/foi-purge-varnish`), and restarting the diff --git a/docs/installing/email.md b/docs/installing/email.md index 44476cefa..6bc3e8351 100644 --- a/docs/installing/email.md +++ b/docs/installing/email.md @@ -36,17 +36,17 @@ Parts of this address are controlled with options in If there is some error inside Rails while processing an email, an exit code `75` is returned to the MTA by the `script/mailin` script. Postfix and Exim (and maybe others) take this as a signal for the MTA to try again later. Additionally, a stacktrace is emailed to `CONTACT_EMAIL`. -[Production]({{ site.baseurl }}/docs/glossary/#production) installs of Alaveteli should make a backup copy of emails sent to the special addresses. You can configure your chosen MTA to backup these in a separate mailbox. +[Production]({{ page.baseurl }}//docs/glossary/#production) installs of Alaveteli should make a backup copy of emails sent to the special addresses. You can configure your chosen MTA to backup these in a separate mailbox. ### Transactional mail Alaveteli also sends emails to users about their requests – letting them know when someone has replied to them, or prompting them to take further action. -Configure the address that these messages are sent from in the [`CONTACT_EMAIL`]({{site.baseurl}}docs/customising/config/#contact_email) option in `config/general.yml`: +Configure the address that these messages are sent from in the [`CONTACT_EMAIL`]({{ page.baseurl }}/docs/customising/config/#contact_email) option in `config/general.yml`: CONTACT_EMAIL = 'team@example.com' -The address in [`CONTACT_EMAIL`]({{ site.baseurl }}docs/customising/config/#contact_email) is also visible in various places on the site so that users can get in touch with the team that runs the site. +The address in [`CONTACT_EMAIL`]({{ page.baseurl }}/docs/customising/config/#contact_email) is also visible in various places on the site so that users can get in touch with the team that runs the site. You must configure your MTA to deliver mail sent to these addresses to the administrators of your site so that they can respond to it. @@ -54,23 +54,23 @@ You must configure your MTA to deliver mail sent to these addresses to the admin Users subscribed to updates from the site – known as `tracks` – receive emails when there is something new of interest to them on the site. -Configure the address that these messages are sent from in the [`TRACK_SENDER_EMAIL`]({{site.baseurl}}docs/customising/config/#track_sender_email) option in `config/general.yml`: +Configure the address that these messages are sent from in the [`TRACK_SENDER_EMAIL`]({{ page.baseurl }}/docs/customising/config/#track_sender_email) option in `config/general.yml`: TRACK_SENDER_EMAIL = 'track@example.com' ### Automatic bounce handling (optional) -As [`CONTACT_EMAIL`]({{ site.baseurl }}docs/customising/config/#contact_email) and [`TRACK_SENDER_EMAIL`]({{site.baseurl}}docs/customising/config/#track_sender_email) appear in the `From:` header of emails sent from Alaveteli, they sometimes receive reply emails, including <a href="{{ site.baseurl }}docs/glossary/#bounce-message">bounce messages</a> and ‘out of office’ notifications. +As [`CONTACT_EMAIL`]({{ page.baseurl }}/docs/customising/config/#contact_email) and [`TRACK_SENDER_EMAIL`]({{ page.baseurl }}/docs/customising/config/#track_sender_email) appear in the `From:` header of emails sent from Alaveteli, they sometimes receive reply emails, including <a href="{{ page.baseurl }}/docs/glossary/#bounce-message">bounce messages</a> and ‘out of office’ notifications. Alaveteli provides a script (`script/handle-mail-replies`) that handles bounce messages and ‘out of office’ notifications and forwards genuine mails to your administrators. It also prevents further track emails being sent to a user email address that appears to have a permanent delivery problem. -To make use of automatic bounce-message handling, set [`TRACK_SENDER_EMAIL`]({{ site.baseurl }}docs/customising/config/#track_sender_email) and [`CONTACT_EMAIL`]({{ site.baseurl }}docs/customising/config/#contact_email) to an address that you will filter through `script/handle-mail-replies`. Messages that are not bounces or out-of-office autoreplies will be forwarded to [`FORWARD_NONBOUNCE_RESPONSES_TO`]({{ site.baseurl }}docs/customising/config/#forward_nonbounce_responses_to), which you should set to a mail alias that points at your list of site administrators. +To make use of automatic bounce-message handling, set [`TRACK_SENDER_EMAIL`]({{ page.baseurl }}/docs/customising/config/#track_sender_email) and [`CONTACT_EMAIL`]({{ page.baseurl }}/docs/customising/config/#contact_email) to an address that you will filter through `script/handle-mail-replies`. Messages that are not bounces or out-of-office autoreplies will be forwarded to [`FORWARD_NONBOUNCE_RESPONSES_TO`]({{ page.baseurl }}/docs/customising/config/#forward_nonbounce_responses_to), which you should set to a mail alias that points at your list of site administrators. -See the MTA-specific instructions for how to do this for [exim]({{ site.baseurl }}docs/installing/email#filter-incoming-messages-to-admin-addresses) and [postfix]({{ site.baseurl }}docs/installing/email#filter-incoming-messages-to-site-admin-addresses). +See the MTA-specific instructions for how to do this for [exim]({{ page.baseurl }}/docs/installing/email#filter-incoming-messages-to-admin-addresses) and [postfix]({{ page.baseurl }}/docs/installing/email#filter-incoming-messages-to-site-admin-addresses). -_Note:_ Bounce handling is not applied to [request emails]({{ site.baseurl }}docs/installing/email#request-mail). Bounce messages from authorities get added to the request page so that the user can see what has happened. Users can ask site admins for help redelivering the request if necessary. +_Note:_ Bounce handling is not applied to [request emails]({{ page.baseurl }}/docs/installing/email#request-mail). Bounce messages from authorities get added to the request page so that the user can see what has happened. Users can ask site admins for help redelivering the request if necessary. --- @@ -142,7 +142,7 @@ In `/etc/postfix/main.cf` update the `mydestination` line (which determines what mydestination = example.com, localhost.localdomain, localhost <div class="attention-box"> -This guide assumes you have set <a href="{{ site.baseurl }}docs/customising/config/#incoming_email_prefix"><code>INCOMING_EMAIL_PREFIX</code></a> to <code>foi+</code> in <code>config/general.yml</code> +This guide assumes you have set <a href="{{ page.baseurl }}/docs/customising/config/#incoming_email_prefix"><code>INCOMING_EMAIL_PREFIX</code></a> to <code>foi+</code> in <code>config/general.yml</code> </div> Pipe all incoming mail where the `To:` address starts with `foi+` to the `alaveteli` pipe (`/var/www/alaveteli/script/mailin`, as specified in `/etc/postfix/master.cf` at the start of this section): @@ -201,7 +201,7 @@ To set up recipient groups for the `postmaster@`, `team@` and `user-support@` em #### Discard unwanted incoming email -Configure postfix to discard any messages sent to the [`BLACKHOLE_PREFIX`]({{ site.baseurl }}docs/customising/config/#blackhole_prefix) address, whose default value is `do-not-reply-to-this-address`: +Configure postfix to discard any messages sent to the [`BLACKHOLE_PREFIX`]({{ page.baseurl }}/docs/customising/config/#blackhole_prefix) address, whose default value is `do-not-reply-to-this-address`: cat >> /etc/aliases <<EOF # We use this for envelope from for some messages where @@ -209,21 +209,21 @@ Configure postfix to discard any messages sent to the [`BLACKHOLE_PREFIX`]({{ si do-not-reply-to-this-address: /dev/null EOF -If you have set [`BLACKHOLE_PREFIX`]({{ site.baseurl }}docs/customising/config/#blackhole_prefix) address, replace `do-not-reply-to-this-address` with the address you have configured. +If you have set [`BLACKHOLE_PREFIX`]({{ page.baseurl }}/docs/customising/config/#blackhole_prefix) address, replace `do-not-reply-to-this-address` with the address you have configured. #### Filter incoming messages to site admin addresses -You can make use of Alaveteli's [automatic bounce handling]({{site.baseurl}}docs/installing/email/#automatic-bounce-handling-optional) to filter bounces sent to [`TRACK_SENDER_EMAIL`]({{site.baseurl}}docs/customising/config/#track_sender_email) -and [`CONTACT_EMAIL`]({{site.baseurl}}docs/customising/config/#contact_email). +You can make use of Alaveteli's [automatic bounce handling]({{ page.baseurl }}/docs/installing/email/#automatic-bounce-handling-optional) to filter bounces sent to [`TRACK_SENDER_EMAIL`]({{ page.baseurl }}/docs/customising/config/#track_sender_email) +and [`CONTACT_EMAIL`]({{ page.baseurl }}/docs/customising/config/#contact_email). <div class="attention-box"> This guide assumes you have set the following in <code>config/general.yml</code>: <ul> - <li><a href="{{site.baseurl}}docs/customising/config/#contact_email">CONTACT_EMAIL</a>: <code>user-support@example.com</code></li> - <li><a href="{{site.baseurl}}docs/customising/config/#track_sender_email">TRACK_SENDER_EMAIL</a>: <code>user-support@example.com</code></li> - <li><a href="{{site.baseurl}}docs/customising/config/#forward_nonbounce_responses_to">FORWARD_NONBOUNCE_RESPONSES_TO</a>: <code>team@example.com</code></li> + <li><a href="{{ page.baseurl }}/docs/customising/config/#contact_email">CONTACT_EMAIL</a>: <code>user-support@example.com</code></li> + <li><a href="{{ page.baseurl }}/docs/customising/config/#track_sender_email">TRACK_SENDER_EMAIL</a>: <code>user-support@example.com</code></li> + <li><a href="{{ page.baseurl }}/docs/customising/config/#forward_nonbounce_responses_to">FORWARD_NONBOUNCE_RESPONSES_TO</a>: <code>team@example.com</code></li> </ul> Change the examples below to the addresses you have configured. @@ -257,8 +257,8 @@ each day), it's good to have them in their own directory. You'll also need to tell Alaveteli where the log files are stored and that they're in postfix format. Update -[`MTA_LOG_PATH`]({{ site.baseurl }}docs/customising/config/#mta_log_path) and -[`MTA_LOG_TYPE`]({{ site.baseurl }}docs/customising/config/#mta_log_type) in `config/general.yml`: +[`MTA_LOG_PATH`]({{ page.baseurl }}/docs/customising/config/#mta_log_path) and +[`MTA_LOG_TYPE`]({{ page.baseurl }}/docs/customising/config/#mta_log_type) in `config/general.yml`: MTA_LOG_PATH: '/var/log/mail/mail.log-*' MTA_LOG_TYPE: "postfix" @@ -340,7 +340,7 @@ delivery report email using the `mail` command on a new server: apt-get install mailutils If emails are not being received by your Alaveteli install, we have some -more troubleshooting tips for incoming mail in [general email troubleshooting]({{ site.baseurl }}docs/installing/email#general-email-troubleshooting). +more troubleshooting tips for incoming mail in [general email troubleshooting]({{ page.baseurl }}/docs/installing/email#general-email-troubleshooting). @@ -460,7 +460,7 @@ To set up recipient groups for the `team@` and `user-support@` email addresses a #### Discard unwanted incoming email -Configure exim to discard any messages sent to the [`BLACKHOLE_PREFIX`]({{ site.baseurl }}docs/customising/config/#blackhole_prefix) address, whose default value is `do-not-reply-to-this-address` +Configure exim to discard any messages sent to the [`BLACKHOLE_PREFIX`]({{ page.baseurl }}/docs/customising/config/#blackhole_prefix) address, whose default value is `do-not-reply-to-this-address` cat >> /var/www/alaveteli/config/aliases <<EOF # We use this for envelope from for some messages where @@ -472,16 +472,16 @@ _Note:_ Replace `/var/www/alaveteli` with the correct path to alaveteli if requi #### Filter incoming messages to admin addresses -You can make use of Alaveteli's [automatic bounce handling]({{site.baseurl}}docs/installing/email/#automatic-bounce-handling-optional) to filter bounces sent to [`TRACK_SENDER_EMAIL`]({{site.baseurl}}docs/customising/config/#track_sender_email) -and [`CONTACT_EMAIL`]({{site.baseurl}}docs/customising/config/#contact_email). +You can make use of Alaveteli's [automatic bounce handling]({{ page.baseurl }}/docs/installing/email/#automatic-bounce-handling-optional) to filter bounces sent to [`TRACK_SENDER_EMAIL`]({{ page.baseurl }}/docs/customising/config/#track_sender_email) +and [`CONTACT_EMAIL`]({{ page.baseurl }}/docs/customising/config/#contact_email). <div class="attention-box"> This guide assumes you have set the following in <code>config/general.yml</code>: <ul> - <li><a href="{{site.baseurl}}docs/customising/config/#contact_email">CONTACT_EMAIL</a>: <code>user-support@example.com</code></li> - <li><a href="{{site.baseurl}}docs/customising/config/#track_sender_email">TRACK_SENDER_EMAIL</a>: <code>user-support@example.com</code></li> - <li><a href="{{site.baseurl}}docs/customising/config/#forward_nonbounce_responses_to">FORWARD_NONBOUNCE_RESPONSES_TO</a>: <code>team@example.com</code></li> + <li><a href="{{ page.baseurl }}/docs/customising/config/#contact_email">CONTACT_EMAIL</a>: <code>user-support@example.com</code></li> + <li><a href="{{ page.baseurl }}/docs/customising/config/#track_sender_email">TRACK_SENDER_EMAIL</a>: <code>user-support@example.com</code></li> + <li><a href="{{ page.baseurl }}/docs/customising/config/#forward_nonbounce_responses_to">FORWARD_NONBOUNCE_RESPONSES_TO</a>: <code>team@example.com</code></li> </ul> Change the examples below to the addresses you have configured. @@ -493,7 +493,7 @@ Change the `user-support` line in `/var/www/alaveteli/config/aliases`: #### Logging -You’ll need to tell Alaveteli where the log files are stored and that they’re in exim format. Update [`MTA_LOG_PATH`]({{ site.baseurl }}docs/customising/config/#mta_log_path) and [`MTA_LOG_TYPE`]({{ site.baseurl }}docs/customising/config/#mta_log_type) in `config/general.yml`: +You’ll need to tell Alaveteli where the log files are stored and that they’re in exim format. Update [`MTA_LOG_PATH`]({{ page.baseurl }}/docs/customising/config/#mta_log_path) and [`MTA_LOG_TYPE`]({{ page.baseurl }}/docs/customising/config/#mta_log_type) in `config/general.yml`: MTA_LOG_PATH: '/var/log/exim4/exim-mainlog-*' MTA_LOG_TYPE: 'exim' @@ -557,8 +557,8 @@ First, you need to check that your MTA is delivering relevant incoming emails to the `script/mailin` command. There are various ways of setting your MTA up to do this; we have documented one way of doing it -[in Exim]({{ site.baseurl }}docs/installing/email/#example-setup-on-exim4), including [a command you can use]({{ site.baseurl }}docs/installing/email/#troubleshooting-exim) to check that the email -routing is set up correctly. We've also documented one way of setting up [Postfix]({{ site.baseurl }}docs/installing/email/#example-setup-on-postfix), with a similar [debugging command]({{ site.baseurl }}docs/installing/email/#troubleshooting-postfix). +[in Exim]({{ page.baseurl }}/docs/installing/email/#example-setup-on-exim4), including [a command you can use]({{ page.baseurl }}/docs/installing/email/#troubleshooting-exim) to check that the email +routing is set up correctly. We've also documented one way of setting up [Postfix]({{ page.baseurl }}/docs/installing/email/#example-setup-on-postfix), with a similar [debugging command]({{ page.baseurl }}/docs/installing/email/#troubleshooting-postfix). Second, you need to test that the mailin script itself is working correctly, by running it from the command line, First, find a diff --git a/docs/installing/index.md b/docs/installing/index.md index c04aaa3ca..269407506 100644 --- a/docs/installing/index.md +++ b/docs/installing/index.md @@ -17,8 +17,8 @@ title: Installing ## Before you start This is important: you need to decide if you are installing Alaveteli for -<a href="{{ site.baseurl }}docs/glossary/#development" class="glossary__link">development</a> or -<a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production</a>. +<a href="{{ page.baseurl }}/docs/glossary/#development" class="glossary__link">development</a> or +<a href="{{ page.baseurl }}/docs/glossary/#production" class="glossary__link">production</a>. A **development** site is one where you're going to change, customise, and perhaps experiment while you get it up and running. You should always do this @@ -30,10 +30,10 @@ A **production** site is different: you want your production site to run as efficiently as possible, so things like caching are swiched on, and debug messages switched off. It's important to be able to deploy changes to a production site quickly and efficiently, so we recommend you consider using a -[deployment mechanism]({{ site.baseurl }}docs/installing/deploy/) too. +[deployment mechanism]({{ page.baseurl }}/docs/installing/deploy/) too. Ideally, you should also have a -<a href="{{ site.baseurl }}docs/glossary/#staging" class="glossary__link">staging site</a>, +<a href="{{ page.baseurl }}/docs/glossary/#staging" class="glossary__link">staging site</a>, which is used solely to test new code in an identical environment to your production site before it goes live. @@ -44,23 +44,23 @@ production server. ## Deployment If you're running a production server, we **strongly recommend** you -use the Capistrano [deployment mechanism]({{ site.baseurl }}docs/installing/deploy/) +use the Capistrano [deployment mechanism]({{ page.baseurl }}/docs/installing/deploy/) that's included with Alaveteli. Set this up and you never have to edit files on those servers, because Capistrano takes care of that for you. ## Installing the core code -* [Install into a Vagrant virtual development environment]({{ site.baseurl }}docs/installing/vagrant/) -- a good choice for development, and playing around with the site. -* [Install on Amazon EC2]({{ site.baseurl }}docs/installing/ami/) using our AMI -* [Use the installation script]({{ site.baseurl }}docs/installing/script/) which does the full installation on your own server -* [Manual installation]({{ site.baseurl }}docs/installing/manual_install/) -- step-by-step instructions +* [Install into a Vagrant virtual development environment]({{ page.baseurl }}/docs/installing/vagrant/) -- a good choice for development, and playing around with the site. +* [Install on Amazon EC2]({{ page.baseurl }}/docs/installing/ami/) using our AMI +* [Use the installation script]({{ page.baseurl }}/docs/installing/script/) which does the full installation on your own server +* [Manual installation]({{ page.baseurl }}/docs/installing/manual_install/) -- step-by-step instructions If you're setting up a development server on MacOS X, we've also got -[MacOS installation instructions]({{ site.baseurl }}docs/installing/macos/). +[MacOS installation instructions]({{ page.baseurl }}/docs/installing/macos/). ## Other installation information Alaveteli needs to be able to send and receive email. If you're installing manually, you need to [setup your -MTA (Mail Transfer Agent) appropriately]({{ site.baseurl }}docs/installing/email/). The other install methods will do this for you. +MTA (Mail Transfer Agent) appropriately]({{ page.baseurl }}/docs/installing/email/). The other install methods will do this for you. -* [Installing the MTA]({{ site.baseurl }}docs/installing/email/) +* [Installing the MTA]({{ page.baseurl }}/docs/installing/email/) diff --git a/docs/installing/macos.md b/docs/installing/macos.md index 2c08be0e5..f6acfcc06 100644 --- a/docs/installing/macos.md +++ b/docs/installing/macos.md @@ -11,7 +11,7 @@ title: Installing on MacOS X help. </p> -Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing/). +Note that there are [other ways to install Alaveteli]({{ page.baseurl }}/docs/installing/). ## MacOS X 10.7 @@ -84,7 +84,7 @@ As of August 22, 2012 or earlier, you can install `mahoro` in Ruby 1.9.3 on OS X ## Alaveteli -The following is mostly from [the manual installation process]({{ site.baseurl}}docs/installing/manual_install). +The following is mostly from [the manual installation process]({{ page.baseurl }}/docs/installing/manual_install). ### Configure database diff --git a/docs/installing/manual_install.md b/docs/installing/manual_install.md index 9cad6b5b9..d4e2a6d17 100644 --- a/docs/installing/manual_install.md +++ b/docs/installing/manual_install.md @@ -10,12 +10,12 @@ title: Manual installation The following instructions describe the step-by-step process for installing Alaveteli. <em>You don't necessarily need to do it this way:</em> it's usually easier to use the - <a href="{{ site.baseurl }}docs/installing/script/">installation script</a> + <a href="{{ page.baseurl }}/docs/installing/script/">installation script</a> or the - <a href="{{ site.baseurl }}docs/installing/ami/">Amazon EC2 AMI</a>. + <a href="{{ page.baseurl }}/docs/installing/ami/">Amazon EC2 AMI</a>. </p> -Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing/). +Note that there are [other ways to install Alaveteli]({{ page.baseurl }}/docs/installing/). <div class="attention-box"> <ul> @@ -30,7 +30,7 @@ Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/ins These instructions assume a 64-bit version of Debian 6 (Wheezy), Debian 7 (Squeeze) or Ubuntu 12.04 LTS (Precise). Debian is the best supported deployment platform. We also -have instructions for [installing on MacOS]({{ site.baseurl }}docs/installing/macos/). +have instructions for [installing on MacOS]({{ page.baseurl }}/docs/installing/macos/). ### Set the locale @@ -309,7 +309,7 @@ Then create the databases: You will need to set up an email server – or Mail Transfer Agent (MTA) – to send and receive emails. -Full configuration for an MTA is beyond the scope of this document -- see the guide for [configuring the Exim4 or Postfix MTAs]({{ site.baseurl }}docs/installing/email/). +Full configuration for an MTA is beyond the scope of this document -- see the guide for [configuring the Exim4 or Postfix MTAs]({{ page.baseurl }}/docs/installing/email/). Note that in development mode mail is handled by [`mailcatcher`](http://mailcatcher.me/) by default so that you can see the mails in a browser. Start mailcatcher by running `bundle exec mailcatcher` in the application directory. @@ -354,7 +354,7 @@ permissions on these databases. As the user needs the ability to turn off constraints whilst running the tests they also need to be a superuser (clarification: a <em>Postgres</em> superuser, not an Alaveteli -<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">superuser</a>). +<a href="{{ page.baseurl }}/docs/glossary/#super" class="glossary__link">superuser</a>). If you don't want your database user to be a superuser, you can add this line to the `test` section in `database.yml` (as seen in `config/database.yml-example`): @@ -362,9 +362,9 @@ to the `test` section in `database.yml` (as seen in `config/database.yml-example ### general.yml -We have a full [guide to Alaveteli configuration]({{ site.baseurl }}docs/customising/config/) which covers all the settings in `config/general.yml`. +We have a full [guide to Alaveteli configuration]({{ page.baseurl }}/docs/customising/config/) which covers all the settings in `config/general.yml`. -_Note:_ If you are setting up Alaveteli to run in production, set the [`STAGING_SITE`]({{ site.baseurl }}docs/customising/config/#staging_site) variable to `0` in `/var/www/alaveteli/config/general.yml` now. +_Note:_ If you are setting up Alaveteli to run in production, set the [`STAGING_SITE`]({{ page.baseurl }}/docs/customising/config/#staging_site) variable to `0` in `/var/www/alaveteli/config/general.yml` now. STAGING_SITE: 0 @@ -558,7 +558,7 @@ Start the application: One of the cron jobs refers to a script at `/etc/init.d/alaveteli-alert-tracks`. This is an init script, which can be generated from the -`config/alert-tracks-debian.ugly` template. This script sends out emails to users subscribed to updates from the site – known as [`tracks`]({{ site.baseurl }}docs/installing/email/#tracks-mail) – when there is something new matching their interests. +`config/alert-tracks-debian.ugly` template. This script sends out emails to users subscribed to updates from the site – known as [`tracks`]({{ page.baseurl }}/docs/installing/email/#tracks-mail) – when there is something new matching their interests. **Template Variables:** @@ -817,11 +817,11 @@ front of Varnish. If you're already using Apache as a web server you could simply use Apache as the SSL terminator. We have some [production server best practice -notes]({{ site.baseurl}}docs/running/server/). +notes]({{ page.baseurl }}/docs/running/server/). ## What next? -Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). +Check out the [next steps]({{ page.baseurl }}/docs/installing/next_steps/). ## Troubleshooting @@ -833,7 +833,7 @@ Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). If there are failures here, something has gone wrong with the preceding steps (see the next section for a common problem and workaround). You might - be able to move on to the [next steps]({{ site.baseurl }}docs/installing/next_steps/), depending on how serious they are, but + be able to move on to the [next steps]({{ page.baseurl }}/docs/installing/next_steps/), depending on how serious they are, but ideally you should try to find out what's gone wrong. @@ -850,7 +850,7 @@ You should then be able to run the tests. Don't forget to restore <code>config/r * **Incoming emails aren't appearing in my Alaveteli install** - See the [general email troubleshooting guide]({{ site.baseurl }}docs/installing/email#general-email-troubleshooting). + See the [general email troubleshooting guide]({{ page.baseurl }}/docs/installing/email#general-email-troubleshooting). * **Various tests fail with "*Your PostgreSQL connection does not support unescape_bytea. Try upgrading to pg 0.9.0 or later.*"** diff --git a/docs/installing/next_steps.md b/docs/installing/next_steps.md index 2b7acbd45..5ebd395aa 100644 --- a/docs/installing/next_steps.md +++ b/docs/installing/next_steps.md @@ -20,11 +20,11 @@ title: Next Steps ## Create a superuser admin account Alaveteli ships with an -<a href="{{site.baseurl}}docs/glossary/#emergency" class="glossary__link">emergency user</a> +<a href="{{ page.baseurl }}/docs/glossary/#emergency" class="glossary__link">emergency user</a> that has access to the admin. So when you've just created a new site, you should sign up to create your own account, then log into admin as the emergency user to promote your new account to be an administrator with -<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">super</a> +<a href="{{ page.baseurl }}/docs/glossary/#super" class="glossary__link">super</a> privilege. As soon as that's done, disable the emergency user, because you don't need to @@ -42,8 +42,8 @@ First, in the browser: * Go to `/profile/sign_in` and create a user by signing up. * Check your email and confirm your account. * Go to `/admin?emergency=1`, log in with the username and password you specified in - [`ADMIN_USERNAME`]({{site.baseurl}}docs/customising/config/#admin_username) - and [`ADMIN_PASSWORD`]({{site.baseurl}}docs/customising/config/#admin_password). + [`ADMIN_USERNAME`]({{ page.baseurl }}/docs/customising/config/#admin_username) + and [`ADMIN_PASSWORD`]({{ page.baseurl }}/docs/customising/config/#admin_password). You can find these settings in `config/general.yml`. * You're now on the Alaveteli admin page. * Click on **Users** (in the navigation menu across the top of the page), and @@ -73,13 +73,13 @@ emergency user access to the admin. On the command line shell, edit * It's important that you change the emergency user's password (and, ideally, the username too) from the values Alavateli ships with, because they are public and hence insecure. In `general.yml`, change - [`ADMIN_PASSWORD`]({{site.baseurl}}docs/customising/config/#admin_password) - (and maybe [`ADMIN_USERNAME`]({{site.baseurl}}docs/customising/config/#admin_username) + [`ADMIN_PASSWORD`]({{ page.baseurl }}/docs/customising/config/#admin_password) + (and maybe [`ADMIN_USERNAME`]({{ page.baseurl }}/docs/customising/config/#admin_username) too) to new, unique values. * Additionally, you can totally disable the emergency user. Under normal operation you don't need it, because from now on you'll be using the admin user you've just created. - Set [`DISABLE_EMERGENCY_USER`]({{site.baseurl}}docs/customising/config/#disable_emergency_user) + Set [`DISABLE_EMERGENCY_USER`]({{ page.baseurl }}/docs/customising/config/#disable_emergency_user) to `true`. * To apply these changes restart the service as a user with root privileges: `sudo service alaveteli restart` @@ -119,8 +119,8 @@ follow the steps described in the previous section. * You should receive the request email -- try replying to it. Your response email should appear in Alaveteli. Not working? Take a look at our - [troubleshooting tips]({{ site.baseurl}}docs/installing/manual_install/#troubleshooting). - If that doesn't sort it out, [get in touch]({{ site.baseurl}}community/) on + [troubleshooting tips]({{ page.baseurl }}/docs/installing/manual_install/#troubleshooting). + If that doesn't sort it out, [get in touch]({{ page.baseurl }}/community/) on the [developer mailing list](https://groups.google.com/forum/#!forum/alaveteli-dev) or [IRC](http://www.irc.mysociety.org/) for help. ## Import Public Authorities @@ -128,7 +128,7 @@ follow the steps described in the previous section. Alaveteli can import a list of public authorities and their contact email addresses from a CSV file. Follow the instructions for -[uploading public authority data]({{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data). +[uploading public authority data]({{ page.baseurl }}/docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data). ## Set the amount of time authorities will be given to respond to requests @@ -137,13 +137,13 @@ have a certain number of days in order to respond to requests. Alaveteli helps requesters by reminding them when their request is overdue for a response according to the law. You can set the number of days an authority is given to respond to a request in the -[`REPLY_LATE_AFTER_DAYS`]({{site.baseurl}}docs/customising/config/#reply_late_after_days), -[`REPLY_VERY_LATE_AFTER_DAYS`]({{site.baseurl}}docs/customising/config/#reply_very_late_after_days) +[`REPLY_LATE_AFTER_DAYS`]({{ page.baseurl }}/docs/customising/config/#reply_late_after_days), +[`REPLY_VERY_LATE_AFTER_DAYS`]({{ page.baseurl }}/docs/customising/config/#reply_very_late_after_days) and -[`SPECIAL_REPLY_VERY_LATE_AFTER_DAYS`]({{site.baseurl}}docs/customising/config/#special_reply_very_late_after_days) +[`SPECIAL_REPLY_VERY_LATE_AFTER_DAYS`]({{ page.baseurl }}/docs/customising/config/#special_reply_very_late_after_days) options in `config/general.yml`. Most laws specify that the days are either working days, or calendar days. You can set this using the -[`WORKING_OR_CALENDAR_DAYS`]({{site.baseurl}}docs/customising/config/#working_or_calendar_days) +[`WORKING_OR_CALENDAR_DAYS`]({{ page.baseurl }}/docs/customising/config/#working_or_calendar_days) option in `config/general.yml`. ## Add some public holidays @@ -153,17 +153,17 @@ Interface introduced in Alaveteli version 0.21 </div> Alaveteli calculates the due dates of requests taking account of the -<a href="{{ site.baseurl }}docs/glossary/#holiday" class="glossary__link">public holidays</a> +<a href="{{ page.baseurl }}/docs/glossary/#holiday" class="glossary__link">public holidays</a> you enter into the admin interface. If you have set the -[`WORKING_OR_CALENDAR_DAYS`]({{site.baseurl}}docs/customising/config/#working_or_calendar_days) +[`WORKING_OR_CALENDAR_DAYS`]({{ page.baseurl }}/docs/customising/config/#working_or_calendar_days) setting for Alaveteli to `working`, the date when a response to a request is officially overdue will be calculated in days that are not weekends or public holidays. If you have set -[`WORKING_OR_CALENDAR_DAYS`]({{site.baseurl}}docs/customising/config/#working_or_calendar_days) +[`WORKING_OR_CALENDAR_DAYS`]({{ page.baseurl }}/docs/customising/config/#working_or_calendar_days) to `calendar`, the date will be calculated in calendar days, but if the due date falls on a public holiday or weekend day, then the due date is considered to be the next week day that isn't a holiday. @@ -176,6 +176,4 @@ once using the **Create holidays from suggestions or iCalendar feed** button. ## Start thinking about customising Alaveteli -Check out [our guide]({{ site.baseurl}}docs/customising/). - - +Check out [our guide]({{ page.baseurl }}/docs/customising/). diff --git a/docs/installing/script.md b/docs/installing/script.md index 72fbd6438..875cf8734 100644 --- a/docs/installing/script.md +++ b/docs/installing/script.md @@ -9,7 +9,7 @@ title: Installation script If you prefer to use your own server, we've provided an installation script which does most of the work for you. </p> -Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing/). +Note that there are [other ways to install Alaveteli]({{ page.baseurl }}/docs/installing/). ## Installing with the installation script @@ -69,7 +69,7 @@ The server will also be configured to accept replies to information request emai ##What next? -Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). +Check out the [next steps]({{ page.baseurl }}/docs/installing/next_steps/). diff --git a/docs/installing/vagrant.md b/docs/installing/vagrant.md index a0b058da5..0e260e81b 100644 --- a/docs/installing/vagrant.md +++ b/docs/installing/vagrant.md @@ -8,10 +8,10 @@ title: Vagrant <a href="https://www.vagrantup.com">Vagrant</a> provides an easy method to set up virtual development environments We bundle an example Vagrantfile in the repository, which runs the - <a href="{{ site.baseurl}}docs/installing/script/">install script</a> for you. + <a href="{{ page.baseurl}}/docs/installing/script/">install script</a> for you. </p> -Note that this is just one of [several ways to install Alaveteli]({{ site.baseurl }}docs/installing/). +Note that this is just one of [several ways to install Alaveteli]({{ page.baseurl }}/docs/installing/). The included steps will use vagrant to create a development environment where you can run the test suite and the development server, and make @@ -23,7 +23,7 @@ scripts will create you a Vagrant VM based on the server edition of Ubuntu 12.04 LTS that contains everything you need to work on Alaveteli. 1. Get a copy of Alaveteli from - <a href="{{ site.baseurl }}docs/glossary/#git" class="glossary__link">GitHub</a>: + <a href="{{ page.baseurl }}/docs/glossary/#git" class="glossary__link">GitHub</a>: # on your machine $ git clone git@github.com:mysociety/alaveteli.git @@ -75,7 +75,7 @@ for full instructions on using Vagrant. ## What next? -Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). +Check out the [next steps]({{ page.baseurl }}/docs/installing/next_steps/). ## Customizing the Vagrant instance diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md index 7c112400c..b05ddb5f4 100644 --- a/docs/running/admin_manual.md +++ b/docs/running/admin_manual.md @@ -8,7 +8,8 @@ title: Administrator's guide <p class="lead"> What is it like running an Alaveteli site? This guide explains what you can expect, and the types of problem that you might encounter. It includes - examples of how mySociety manages their own <a href="/docs/glossary/#foi" + examples of how mySociety manages their own + <a href="{{ page.baseurl }}/docs/glossary/#foi" class="glossary__link">Freedom of Information</a> site, <a href="https://www.whatdotheyknow.com">whatdotheyknow.com</a>. </p> @@ -57,7 +58,7 @@ WhatDoTheyKnow usually has about 3 active volunteers at any one time managing the support, plus a few other less active people who help out at different times. -Administration tasks can be split into [**maintenance**]({{ site.baseurl }}docs/running/admin_manual/#maintenance) and [**user support**]({{ site.baseurl }}docs/running/admin_manual/#user-support). +Administration tasks can be split into [**maintenance**]({{ page.baseurl }}/docs/running/admin_manual/#maintenance) and [**user support**]({{ page.baseurl }}/docs/running/admin_manual/#user-support). The boundaries of these tasks is in fact quite blurred; the main distinction is that the former happen exclusively through the web admin interface, whereas the latter are mediated by email directly with end users (but often result in @@ -312,13 +313,13 @@ line, and piping the contents of that file into the mail handling script. e.g. ### Administrator privileges and accessing the admin interface -The <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">administrative interface</a> +The <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">administrative interface</a> is at the URL `/admin`. Only users who are -<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">administrators</a> +<a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">administrators</a> can access the admin interface. To make a user an administrator on a brand new site, -[follow these steps]({{ site.baseurl }}docs/installing/next_steps/#create-a-superuser-admin-account). +[follow these steps]({{ page.baseurl }}/docs/installing/next_steps/#create-a-superuser-admin-account). If you're already an administrator, you can grant other users administrator privilege too. Go to `/admin/users` or click on **Users** at the top of @@ -336,20 +337,20 @@ have extra privileges in the main website front end. Administrators can: <div class="attention-box warning"> It is possible completely to override the administrator authentication by setting - <code><a href="{{ site.baseurl }}docs/customising/config/#skip_admin_auth">SKIP_ADMIN_AUTH</a></code> + <code><a href="{{ page.baseurl }}/docs/customising/config/#skip_admin_auth">SKIP_ADMIN_AUTH</a></code> to <code>true</code> in <code>general.yml</code>. Never do this, unless you - are working on a <a href="{{ site.baseurl }}docs/glossary/#development" + are working on a <a href="{{ page.baseurl }}/docs/glossary/#development" class="glossary__link">development</a> server. </div> ### Removing a message from the holding pen Alaveteli puts incoming messages (that is, -<a href="{{ site.baseurl }}docs/glossary/#reponse" class="glossary__link">responses</a>) +<a href="{{ page.baseurl }}/docs/glossary/#reponse" class="glossary__link">responses</a>) into the -<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a> +<a href="{{ page.baseurl }}/docs/glossary/#holding_pen" class="glossary__link">holding pen</a> if their `To:` email addresses can't automatically be associated with a -<a href="{{ site.baseurl }}docs/glossary/#reponse" class="glossary__link">request</a>. +<a href="{{ page.baseurl }}/docs/glossary/#reponse" class="glossary__link">request</a>. The two most common reasons for this are: @@ -361,7 +362,7 @@ When this happens, the messages wait in the holding pen until an administrator redelivers them to the correct request, or else deletes them. To do this, log into the -The <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a> +The <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a> at `/admin`. If there are any messages in the holding pen, you'll see this message under the title *Things to do*: @@ -417,13 +418,13 @@ in the holding pen, and is shown instead on the public request page. ### Rejecting spam that arrives in the holding pen Alaveteli maintains a -<a href="{{ site.baseurl }}docs/glossary/#spam-address-list" class="glossary__link">spam address list</a>. +<a href="{{ page.baseurl }}/docs/glossary/#spam-address-list" class="glossary__link">spam address list</a>. Any incoming message to an email address on that list *that would otherwise be put in the holding pen* will be rejected and won't appear in the admin. If you see spam messages in the -<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a>, +<a href="{{ page.baseurl }}/docs/glossary/#holding_pen" class="glossary__link">holding pen</a>, check if they are being sent to a *specific* email address. If they are, that email address has become a "spam-target" and you should add it to the spam address list. Thereafter, Alaveteli will automatically reject any messages that @@ -434,7 +435,7 @@ messages end up in the holding pen) becomes a spam-target once it's been harvested by spammers. There are several reasons why such an invalid address might exist — perhaps it was mis-spelled in a manual reply, for example. Our experience from running -<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> +<a href="{{ page.baseurl }}/docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> is that you can safely dismiss incoming email to such addresses once they have been targeted in this way. Legitimate emails that arrive in the holding pen tend to be unique errors (for example, missing the last character of the email @@ -471,7 +472,7 @@ this address. Note that if you are seeing consistent spam email in your holding pen, you should also consider implementing (or increasing) the anti-spam measures running in your -<a href="{{ site.baseurl }}docs/glossary/#mta" class="glossary__link">MTA</a>. +<a href="{{ page.baseurl }}/docs/glossary/#mta" class="glossary__link">MTA</a>. ### Creating, changing and uploading public authority data @@ -554,7 +555,7 @@ unrecognised column name, the import will fail. <td><em>yes</em></td> <td> The URL of the authority's - <a href="{{ site.baseurl }}docs/glossary/#publication-scheme" class="glossary__link">publication scheme</a>, + <a href="{{ page.baseurl }}/docs/glossary/#publication-scheme" class="glossary__link">publication scheme</a>, if they have one </td> </tr> @@ -563,7 +564,7 @@ unrecognised column name, the import will fail. <td><em>yes</em></td> <td> The URL of the authority's - <a href="{{ site.baseurl }}docs/glossary/#disclosure-log" class="glossary__link">disclosure log</a>, + <a href="{{ page.baseurl }}/docs/glossary/#disclosure-log" class="glossary__link">disclosure log</a>, if they have one </td> </tr> @@ -588,10 +589,10 @@ unrecognised column name, the import will fail. changed. This means you only really need to include data you want to update. * Columns with "i18n suffix" can accept - <a href="{{ site.baseurl }}docs/glossary/#i18n" class="glossary__link">internationalised</a> + <a href="{{ page.baseurl }}/docs/glossary/#i18n" class="glossary__link">internationalised</a> names. Add a full stop followed by the language code, for example: `name.es` for Spanish (`es`). This *must* be a locale you've declared in - [`AVAILABLE_LOCALES`]({{ site.baseurl }}docs/customising/config/#available_locales). + [`AVAILABLE_LOCALES`]({{ page.baseurl }}/docs/customising/config/#available_locales). If you don't specify an i18n suffix, the default language for your site is assumed. * You can specify a blank entry in the CSV file by having no character @@ -689,14 +690,14 @@ Enter some text in the in the ‘Ban text’ box to explain why they have been b ### Allowing a user to make more requests -Alaveteli has a config setting <code><a href="{{ site.baseurl }}docs/customising/config/#max_requests_per_user_per_day">MAX_REQUESTS_PER_USER_PER_DAY</a></code>, +Alaveteli has a config setting <code><a href="{{ page.baseurl }}/docs/customising/config/#max_requests_per_user_per_day">MAX_REQUESTS_PER_USER_PER_DAY</a></code>, which determines the maximum number of requests that a normal user can make in a day. If they try to make more than this number of requests within a 24 hour period, they will see a message telling them that they have hit the limit, and encouraging them to use the contact form if they feel they have a good reason to ask for the request limit to be lifted. -To lift the request limit for a particular user, go to the <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin +To lift the request limit for a particular user, go to the <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Users**, then click on the name of the user you want to lift the request limit for. Click the **Edit** button. Tick the checkbox **No rate limit**, and click the **Save** button. @@ -716,12 +717,12 @@ Users can choose which authorities to include in a batch requests. They can eve </div> To enable batch requests on your site, first you must set -<code><a href="{{ site.baseurl }}docs/customising/config/#allow_batch_requests">ALLOW_BATCH_REQUESTS</a></code> +<code><a href="{{ page.baseurl }}/docs/customising/config/#allow_batch_requests">ALLOW_BATCH_REQUESTS</a></code> to <code>true</code> in <code>general.yml</code>. This does not allow anyone to make batch requests yet. You must still enable this for each user on an individual basis. To do this, go to the -<a href="{{ site.baseurl }}docs/glossary/#admin" +<a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Users**, then click on the name of the user who wants to make batch requests. Click the **Edit** button. Tick the checkbox **Can make batch requests**, and @@ -740,18 +741,18 @@ an existing request to that authority to the new email address. Alternatively, a user may send a request to the wrong authority. In that situation, you can change the authority on the request and then resend it to the correct authority. For instructions, see -[resending a request or sending it to a different authority]({{ site.baseurl }}docs/running/requests/#resending-a-request-or-sending-it-to-a-different-authority). +[resending a request or sending it to a different authority]({{ page.baseurl }}/docs/running/requests/#resending-a-request-or-sending-it-to-a-different-authority). ### Hiding a request If a request contains vexatious or inappropriate content, is libellous, or is not a valid -<a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary__link">Freedom of Information</a> +<a href="{{ page.baseurl }}/docs/glossary/#foi" class="glossary__link">Freedom of Information</a> request at all, you may want to hide it. A hidden request is still visible to you and the other administrators, and (optionally) the requester themselves. For instructions, see -[hiding a request]({{ site.baseurl }}docs/running/requests/#hiding-a-request). +[hiding a request]({{ page.baseurl }}/docs/running/requests/#hiding-a-request). Responses to a hidden request will be accepted in the normal way, but because they are added to the request's page, they too will be hidden. @@ -759,7 +760,7 @@ they are added to the request's page, they too will be hidden. ### Deleting a request You can delete a request from the site. For instructions, see -[deleting a request]({{ site.baseurl }}docs/running/requests/#deleting-a-request). +[deleting a request]({{ page.baseurl }}/docs/running/requests/#deleting-a-request). Responses to a deleted request will be sent to the holding pen. diff --git a/docs/running/categories_and_tags.md b/docs/running/categories_and_tags.md index 8f36ae472..e1192f84d 100644 --- a/docs/running/categories_and_tags.md +++ b/docs/running/categories_and_tags.md @@ -8,12 +8,12 @@ title: Categories & tags <p class="lead"> Use tags to arrange - <a href="{{ site.baseurl }}docs/glossary/#authority" + <a href="{{ page.baseurl }}/docs/glossary/#authority" class="glossary__link">authorities</a> into categories, or to associate related authorities with each other. This helps your users find the right authority for the - <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a> - (or <a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">response</a>) + <a href="{{ page.baseurl }}/docs/glossary/#request" class="glossary__link">request</a> + (or <a href="{{ page.baseurl }}/docs/glossary/#response" class="glossary__link">response</a>) they are interested in. </p> @@ -26,7 +26,7 @@ Admin interface introduced in Alaveteli version 0.20 Alaveteli lets you organise your authorities into *categories*. Categories can themselves belong to *category headings*. For example, some of the categories and headings on -<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>'s +<a href="{{ page.baseurl }}/docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>'s <a href="https://www.whatdotheyknow.com/body/list/all">View authorities</a> page look like this: > * **Media and culture** @@ -57,7 +57,7 @@ users find the specific authorities they are looking for. Try to use simple but descriptive words for tags. Tags cannot contain spaces (use an underscore if you need to, <code>like_this</code>). Remember that tags will be seen and used by the public (for example, in the - <a href="{{ site.baseurl }}docs/glossary/#advanced-search" class="glossary__link">advanced search</a>). + <a href="{{ page.baseurl }}/docs/glossary/#advanced-search" class="glossary__link">advanced search</a>). </div> ### Adding a new category @@ -113,7 +113,7 @@ of these tags. <td> This is a test/dummy authority. It is not displayed to the public on your main site, and it is not included when you - <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">export authorities in CSV format</a>. + <a href="{{ page.baseurl }}/docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">export authorities in CSV format</a>. </td> </tr> <tr> @@ -130,7 +130,7 @@ of these tags. <code>not_apply</code> </td> <td> - <a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary__link">Freedom of Information</a> + <a href="{{ page.baseurl }}/docs/glossary/#foi" class="glossary__link">Freedom of Information</a> law does not apply to this authority: new requests cannot be sent to an authority with this tag. </td> @@ -142,7 +142,7 @@ of these tags. <td> <em>Custom example:</em> (see below)<br> On our UK installation of Alaveteli, - <a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>, + <a href="{{ page.baseurl }}/docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>, this tag indicates that the authority is subject to an alternative law (Environment Information Regulations, rather than the Freedom of Information), which means Alaveteli must change the wording of these @@ -155,7 +155,7 @@ of these tags. </td> <td> <em>Custom example:</em> (see below)<br> - <a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> + <a href="{{ page.baseurl }}/docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> applies a different definition of "late" if an authority has the <code>school</code> tag. </td> </tr> @@ -169,10 +169,10 @@ categories. If you are a developer, and you want to add special behaviour to your site based on your own tags, you need to add custom code, which should probably go in your own -<a href="{{ site.baseurl}}docs/glossary/#theme" class="glossary__link">theme</a>. +<a href="{{ page.baseurl }}/docs/glossary/#theme" class="glossary__link">theme</a>. For example, in the UK, schools are granted special concession in the law to allow for requests that are made out of term-time. Alaveteli handles this by using the -[`SPECIAL_REPLY_VERY_LATE_AFTER_DAYS`]({{ site.baseurl }}docs/customising/config/#special_reply_very_late_after_days) +[`SPECIAL_REPLY_VERY_LATE_AFTER_DAYS`]({{ page.baseurl }}/docs/customising/config/#special_reply_very_late_after_days) config value if the authority has the `school` tag. See [`is_school?`](https://github.com/mysociety/alaveteli/blob/f0bbeb4abf4bf07e5cfb46668f39bbff72ed7210/app/models/public_body.rb#L391) @@ -183,7 +183,7 @@ for the source code. ## Searching with tags Alaveteli's -<a href="{{ site.baseurl }}docs/glossary/#advanced-search" class="glossary__link">advanced search</a> +<a href="{{ page.baseurl }}/docs/glossary/#advanced-search" class="glossary__link">advanced search</a> feature (which is available to all your users) can search for specific tags. So if you add useful tags and publicise them, your users can use them to find related authorities. For example, see the <a @@ -191,7 +191,7 @@ href="https://www.whatdotheyknow.com/advancedsearch">advanced search on WhatDoTheyKnow</a> to see this at work. You can add reference numbers or specific values to tags using a colon. On -<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> +<a href="{{ page.baseurl }}/docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> we tag all authorities that are charities with the tag `charity:123456` (where 123456 is the authority's registered charity number). diff --git a/docs/running/holding_pen.md b/docs/running/holding_pen.md index 5b7f08bec..535c17dd8 100644 --- a/docs/running/holding_pen.md +++ b/docs/running/holding_pen.md @@ -8,15 +8,15 @@ title: The holding pen <p class="lead"> The <em>holding pen</em> is where Alaveteli puts any incoming - <a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">responses</a> + <a href="{{ page.baseurl }}/docs/glossary/#response" class="glossary__link">responses</a> that can't be matched to a - <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a> + <a href="{{ page.baseurl }}/docs/glossary/#request" class="glossary__link">request</a> automatically. </p> Alaveteli works by emailing requests to the correct target -<a href="{{ site.baseurl }}docs/glossary/#authority" class="glossary__link">authority</a>. +<a href="{{ page.baseurl }}/docs/glossary/#authority" class="glossary__link">authority</a>. That email message is sent from a unique email address — that is, an email address that is associated with that single request (technically, Alaveteli hashes the request ID to generate a unique address and uses this as @@ -25,7 +25,7 @@ the `Reply-to:` address). So whenever an authority replies (by email) to a request that Alaveteli has sent, that response will be addressed to that request's unique email address. The email is received by your installation's -<a href="{{ site.baseurl}}docs/glossary/#mta" class="glossary__link">MTA</a>, +<a href="{{ page.baseurl }}/docs/glossary/#mta" class="glossary__link">MTA</a>, and is passed on to Alaveteli. In this way, incoming messages are easily matched with the request they are responses to — this is important because your site displays the responses underneath their original request, on @@ -34,11 +34,11 @@ the request's page. Normally, this works fine. But sometimes things go wrong, and a message comes in that can't be matched with a request. When this happens, Alaveteli puts the message in the -<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding +<a href="{{ page.baseurl }}/docs/glossary/#holding_pen" class="glossary__link">holding pen </a>. Messages wait in the holding pen until an -<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a> +<a href="{{ page.baseurl }}/docs/glossary/#super" class="glossary__link">administrator</a> redelivers them to the correct request, or else deletes them. ## Why messages end up in the holding pen @@ -61,7 +61,7 @@ There are several reasons why a message might end up in the holding pen: deliberate attempt to send spam. * **the response is to a request that has been deleted**<br> - If you [delete a request]({{ site.baseurl }}docs/running/requests/#deleting-a-request), + If you [delete a request]({{ page.baseurl }}/docs/running/requests/#deleting-a-request), Alaveteli cannot deliver responses to it. * **the response has been rejected and rejections are set to go to the holding pen**<br> @@ -72,12 +72,12 @@ There are several reasons why a message might end up in the holding pen: reasons — for example, if a response is sent from an unrecognised email address for a request whose *Allow new responses from* setting is `authority_only`. See instructions on - [how to manage requests]({{site.baseurl}}docs/running/requests/) for details. + [how to manage requests]({{ page.baseurl }}/docs/running/requests/) for details. ## What to do: redeliver or delete You need to be an -<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a> +<a href="{{ page.baseurl }}/docs/glossary/#super" class="glossary__link">administrator</a> to modify the holding pen. There are two things you can do to a message in the holding pen: @@ -90,12 +90,12 @@ There are two things you can do to a message in the holding pen: If the message is not a response, you can delete it. For instructions, see -[removing a message from the holding pen]({{ site.baseurl }}docs/running/admin_manual/#removing-a-message-from-the-holding-pen). +[removing a message from the holding pen]({{ page.baseurl }}/docs/running/admin_manual/#removing-a-message-from-the-holding-pen). If the `To:` address does not belong to a valid request and the message is clearly spam you can add that email address to Alaveteli's -<a href="{{site.baseurl}}#spam-address-list" class="glossary__link">spam address list</a>. +<a href="{{ page.baseurl }}/#spam-address-list" class="glossary__link">spam address list</a>. Subsequent messages to that address will be automatically rejected — for instructions see -[rejecting spam that arrives in the holding pen]({{ site.baseurl }}docs/running/admin_manual/#rejecting-spam-that-arrives-in-the-holding-pen). +[rejecting spam that arrives in the holding pen]({{ page.baseurl }}/docs/running/admin_manual/#rejecting-spam-that-arrives-in-the-holding-pen). diff --git a/docs/running/index.md b/docs/running/index.md index bbf30d3b9..c84a74427 100644 --- a/docs/running/index.md +++ b/docs/running/index.md @@ -11,19 +11,19 @@ title: Running </p> Alaveteli is not just software. To run a successful -<a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary__link">Freedom of Information</a> +<a href="{{ page.baseurl }}/docs/glossary/#foi" class="glossary__link">Freedom of Information</a> site, you need to make sure day-to-day tasks get done too. Most Alaveteli sites are run by a team who allocate some time every day to user support and generally keeping the project up to date. -* The [administrator's guide]({{ site.baseurl }}docs/running/admin_manual/) describes +* The [administrator's guide]({{ page.baseurl }}/docs/running/admin_manual/) describes what you need to do and know to run your site -* The [redaction guide]({{ site.baseurl }}docs/running/redaction/) includes some +* The [redaction guide]({{ page.baseurl }}/docs/running/redaction/) includes some examples of Alaveteli's ability to redact sensitive information * We've prepared a checklist of - [things to consider]({{ site.baseurl }}docs/running/server/) + [things to consider]({{ page.baseurl }}/docs/running/server/) when setting up your production server diff --git a/docs/running/redaction.md b/docs/running/redaction.md index 6ab8fed86..1e6542873 100644 --- a/docs/running/redaction.md +++ b/docs/running/redaction.md @@ -7,7 +7,7 @@ title: Redacting Sensitive Information In some countries, local requirements mean that requests need to contain personal information such as the address or ID number of the person asking for information. Usually requesters do not want this information to be displayed to the general public. -Alaveteli has some ability to deal with this through the use of <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rules</a>. +Alaveteli has some ability to deal with this through the use of <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rules</a>. The [theme](https://github.com/mysociety/derechoapreguntar-theme) we'll use as an example requires a National Identity Card Number and what's known as General Law in Nicaragua (Date of Birth, Domicile, Occupation and Marital Status). @@ -30,13 +30,13 @@ When a request is made the user's ID Number is now added to the footer of the ou  -At this point we haven't added any <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rules</a>. When the authority replies it is unlikely that the responder will remove the quoted section of the email: +At this point we haven't added any <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rules</a>. When the authority replies it is unlikely that the responder will remove the quoted section of the email:  -We could add a <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> for the individual request, but as every request will contain a user's ID Number its better to add some code to do do it automatically. +We could add a <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> for the individual request, but as every request will contain a user's ID Number its better to add some code to do do it automatically. -To illustrate this we'll patch the `User` model with a callback that creates a <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> when the user is created and updated. +To illustrate this we'll patch the `User` model with a callback that creates a <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> when the user is created and updated. # THEME_ROOT/lib/model_patches.rb User.class_eval do @@ -54,7 +54,7 @@ To illustrate this we'll patch the `User` model with a callback that creates a < end end -You can see the new <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> in the admin interface: +You can see the new <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> in the admin interface:  @@ -66,9 +66,9 @@ It also gets redacted if the public body use the ID Number in the main email bod  -A <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">censor rule</a> added to a user only gets applied to correspondence on requests created by that user. It does not get applied to annotations made by the user. +A <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">censor rule</a> added to a user only gets applied to correspondence on requests created by that user. It does not get applied to annotations made by the user. -**Warning:** Redaction in this way requires the sensitive text to be in exactly the same format as the <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a>. If it differs even slightly, the redaction can fail. If the public body was to remove the hyphens from the number it would not be redacted: +**Warning:** Redaction in this way requires the sensitive text to be in exactly the same format as the <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a>. If it differs even slightly, the redaction can fail. If the public body was to remove the hyphens from the number it would not be redacted:  @@ -102,7 +102,7 @@ Note that the information is now contained in a specially formatted block of tex  -This allows a <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> to match the special formatting and remove anything contained within. This <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> is global, so it will act on matches in all requests. +This allows a <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> to match the special formatting and remove anything contained within. This <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> is global, so it will act on matches in all requests. # THEME_ROOT/lib/censor_rules.rb # If not already created, make a CensorRule that hides personal information @@ -126,7 +126,7 @@ In this case the authority has revealed the user's Date of Birth and Domicile:  -Its really difficult to add a <a href="{{site.baseurl}}docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> to remove this type of information. One suggestion might be to remove all mentions of the user's Date of Birth, but you would have to account for [every type of date format](http://en.wikipedia.org/wiki/Calendar_date#Date_format). Likewise, you could redact all occurrences of the user's Domicile, but if they a question about their local area (very likely) the request would become unintelligible. +Its really difficult to add a <a href="{{ page.baseurl }}/docs/glossary/#censor-rule" class="glossary__link">Censor Rule</a> to remove this type of information. One suggestion might be to remove all mentions of the user's Date of Birth, but you would have to account for [every type of date format](http://en.wikipedia.org/wiki/Calendar_date#Date_format). Likewise, you could redact all occurrences of the user's Domicile, but if they a question about their local area (very likely) the request would become unintelligible.  diff --git a/docs/running/requests.md b/docs/running/requests.md index e554fe763..3b4c6e44e 100644 --- a/docs/running/requests.md +++ b/docs/running/requests.md @@ -8,17 +8,17 @@ title: Managing requests <p class="lead"> Alaveteli makes it easy for a user to make a - <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a>. + <a href="{{ page.baseurl }}/docs/glossary/#request" class="glossary__link">request</a>. As an - <a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a>, + <a href="{{ page.baseurl }}/docs/glossary/#super" class="glossary__link">administrator</a>, there are some things about that request you can change once it’s been created. </p> A request is automatically created when a user submits and (where necessary) confirms it. Alaveteli sends it to the -<a href="{{ site.baseurl }}docs/glossary/#authority" class="glossary__link">authority</a> +<a href="{{ page.baseurl }}/docs/glossary/#authority" class="glossary__link">authority</a> responsible and handles any -<a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">responses</a>. +<a href="{{ page.baseurl }}/docs/glossary/#response" class="glossary__link">responses</a>. Usually this process runs without needing any intervention from an administrator. But sometimes you'll want to change some aspect of the request, or the way Alaveteli is handling it. @@ -35,7 +35,7 @@ or the way Alaveteli is handling it. ## What state is the request in? Every request moves through a series of -<a href="{{ site.baseurl }}docs/glossary/#state" class="glossary__link">states</a>, +<a href="{{ page.baseurl }}/docs/glossary/#state" class="glossary__link">states</a>, indicating its progress. Usually a new request will be in the `waiting_response` state until something happens to change that — for example, a response is received. @@ -87,7 +87,7 @@ for how to change these settings. ## Changing things about a request To change any of these settings, go to the -<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>, +<a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Requests**, then click on the title of the request you want to affect. Click the **Edit metadata** button. @@ -179,12 +179,12 @@ Click the **Edit metadata** button. </li> <li> <code>holding pen</code>: responses are put in the - <a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a> + <a href="{{ page.baseurl }}/docs/glossary/#holding_pen" class="glossary__link">holding pen</a> for an administrator to deal with </li> <li> <code>blackhole</code>: responses are destroyed by being sent to a - <a href="{{ site.baseurl }}docs/glossary/#blackhole" class="glossary__link">black hole</a> + <a href="{{ page.baseurl }}/docs/glossary/#blackhole" class="glossary__link">black hole</a> </li> </ul> </td> @@ -194,7 +194,7 @@ Click the **Edit metadata** button. What state is it in? </td> <td> - See <a href="{{ site.baseurl }}docs/customising/states/">more about + See <a href="{{ page.baseurl }}/docs/customising/states/">more about request states</a>, which can be customised for your installation. <p> You can force the state of the request by choosing it explicitly. @@ -240,10 +240,10 @@ Click the **Edit metadata** button. </p> <p> Although it’s a little more complex than tags on requests, - <a href="{{ site.baseurl }}docs/glossary/#category" class="glossary__link">categories</a> + <a href="{{ page.baseurl }}/docs/glossary/#category" class="glossary__link">categories</a> also use tags: see - <a href="{{ site.baseurl }}docs/running/categories_and_tags/">more about tags</a> + <a href="{{ page.baseurl }}/docs/running/categories_and_tags/">more about tags</a> for a little more information. </p> </td> @@ -258,12 +258,12 @@ a user may send a request to the wrong authority. In that situation, you can change the authority on the request and then resend it to the correct authority. To resend a request, go to -the <a href="{{ site.baseurl }}docs/glossary/#admin" +the <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Requests**, then click on the name of the request you want to change. Go to the **Outgoing messages** heading. Click the chevron next to the first outgoing message, which is the initial request. A panel of information about that message will appear. Click on the **Resend** button. To send a request to a different authority, go to -the <a href="{{ site.baseurl }}docs/glossary/#admin" +the <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Requests**, then click on the name of the request you want to change. In the **Request metadata** section, there is a line which shows the authority. Click the @@ -285,7 +285,7 @@ You can hide an entire request. Typically you do this if it's not a valid Freedom of Information request (for example, a request for personal information), or if it is vexatious. -Go to the <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>, +Go to the <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Requests**, then click on the title of the request you want. You can hide it in one of two ways: @@ -344,12 +344,12 @@ destroyed as well. <a href="#hiding-a-request">hide the request</a> instead. </div> -Go to the <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>, +Go to the <a href="{{ page.baseurl }}/docs/glossary/#admin" class="glossary__link">admin interface</a>, click on **Requests**, then click on the title of the request you want to delete. Click the **Edit metadata** button. Click on the red **Destroy request entirely** button at the bottom of the page. Responses to a deleted request will be sent to the -<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a>. +<a href="{{ page.baseurl }}/docs/glossary/#holding_pen" class="glossary__link">holding pen</a>. diff --git a/docs/running/server.md b/docs/running/server.md index da1312ac3..4a36aff41 100644 --- a/docs/running/server.md +++ b/docs/running/server.md @@ -25,7 +25,7 @@ ask us about hosting. ## Cron jobs Don't forget to set up the cron jobs as outlined in the -[installation instructions]({{ site.baseurl }}docs/installing/manual_install/). +[installation instructions]({{ page.baseurl }}/docs/installing/manual_install/). ## Webserver configuration @@ -34,7 +34,7 @@ We recommend running your site behind [Passenger](https://www.phusionpassenger.com) or [Nginx](http://wiki.nginx.org/Main) + [Thin](http://code.macournoyer.com/thin/). If you're using Passenger, refer to the -[installation instructions]({{ site.baseurl }}docs/installing/manual_install/) +[installation instructions]({{ page.baseurl }}/docs/installing/manual_install/) regarding `PassengerMaxPoolSize`, which you should experiment with to match your available RAM. It is very unlikely that you'll ever need a pool larger than [Passenger's @@ -47,23 +47,23 @@ Alaveteli ships with a ## Security -You _must_ change all key-related [config settings]({{ site.baseurl }}docs/customising/config/) +You _must_ change all key-related [config settings]({{ page.baseurl }}/docs/customising/config/) in `general.yml` from their default values. This includes (but may not be limited to!) these settings: -* [`INCOMING_EMAIL_SECRET`]({{ site.baseurl }}docs/customising/config/#incoming_email_secret) -* [`ADMIN_USERNAME`]({{ site.baseurl }}docs/customising/config/#admin_username) -* [`ADMIN_PASSWORD`]({{ site.baseurl }}docs/customising/config/#admin_password) -* [`COOKIE_STORE_SESSION_SECRET`]({{ site.baseurl }}docs/customising/config/#cookie_store_session_secret) -* [`RECAPTCHA_PUBLIC_KEY`]({{ site.baseurl }}docs/customising/config/#recaptcha_public_key) -* [`RECAPTCHA_PRIVATE_KEY`]({{ site.baseurl }}docs/customising/config/#recaptcha_private_key) +* [`INCOMING_EMAIL_SECRET`]({{ page.baseurl }}/docs/customising/config/#incoming_email_secret) +* [`ADMIN_USERNAME`]({{ page.baseurl }}/docs/customising/config/#admin_username) +* [`ADMIN_PASSWORD`]({{ page.baseurl }}/docs/customising/config/#admin_password) +* [`COOKIE_STORE_SESSION_SECRET`]({{ page.baseurl }}/docs/customising/config/#cookie_store_session_secret) +* [`RECAPTCHA_PUBLIC_KEY`]({{ page.baseurl }}/docs/customising/config/#recaptcha_public_key) +* [`RECAPTCHA_PRIVATE_KEY`]({{ page.baseurl }}/docs/customising/config/#recaptcha_private_key) You should consider running the admin part of the site over HTTPS. This can be achieved with rewrite rules that redirect URLs beginning with `/admin`. ## Email configuration -See the [configuration for exim or postfix]({{ site.baseurl }}docs/installing/email/) for +See the [configuration for exim or postfix]({{ page.baseurl }}/docs/installing/email/) for setting up your Mail Transfer Agent (MTA). It is possible to use other MTAs — if you use a different one, the documentation there should provide you with enough information to get started. If this applies to you, please add to the @@ -77,7 +77,7 @@ deliverability of your email: href="http://wiki.asrg.sp.am/wiki/Feedback_loop_links_for_some_email_providers">feedback loops</a> with the main email providers (Hotmail and Yahoo! are recommended) * Especially if deploying from Amazon EC2, use an external SMTP relay for - sending outgoing mail. See [Alaveteli EC2 AMI]( {{ site.baseurl }}docs/installing/ami/) + sending outgoing mail. See [Alaveteli EC2 AMI]( {{ page.baseurl }}/docs/installing/ami/) for more suggestions. ## Backup @@ -85,7 +85,7 @@ deliverability of your email: Most of the data for the site lives in the production database. The exception is the raw incoming email data, which is stored on the filesystem, as specified in the setting -[`RAW_EMAILS_LOCATION`]({{ site.baseurl }}docs/customising/config/#raw_emails_location) +[`RAW_EMAILS_LOCATION`]({{ page.baseurl }}/docs/customising/config/#raw_emails_location) setting in `config/general.yml`. Refer to the [Postgres diff --git a/docs/running/upgrading.md b/docs/running/upgrading.md index 81af8289f..39c18163c 100644 --- a/docs/running/upgrading.md +++ b/docs/running/upgrading.md @@ -8,14 +8,14 @@ Upgrading Alaveteli <p class="lead"> Alaveteli is under active development — don’t let the version you’re running get too far behind our latest - <a href="{{site.baseurl}}docs/glossary/#release" class="glossary__link">release</a>. + <a href="{{ page.baseurl }}/docs/glossary/#release" class="glossary__link">release</a>. This page describes how to keep your site up to date. </p> ## How to upgrade the code * If you're using Capistrano for deployment, - simply [deploy the code]({{site.baseurl}}docs/installing/deploy/#usage): + simply [deploy the code]({{ page.baseurl }}/docs/installing/deploy/#usage): set the repo and branch in `deploy.yml` to be the version you want. We recommend you set this to the explicit tag name (for example, `0.18`, and not `master`) so there's no risk of you accidentally deploying @@ -24,7 +24,7 @@ Upgrading Alaveteli ## Run the post-deploy script -Unless you're [using Capistrano for deployment]({{site.baseurl}}docs/installing/deploy/), +Unless you're [using Capistrano for deployment]({{ page.baseurl }}/docs/installing/deploy/), you should always run the script `scripts/rails-post-deploy` after each deployment. This runs any database migrations for you, plus various other things that can be automated for deployment. @@ -55,7 +55,7 @@ version numbering when it reaches `1.0.0`. The developer team policy is that the `master` branch in git should always contain the latest stable release -- so you'll be up to date if you pull from the `master` branch. However, on your -<a href="{{site.baseurl}}docs/glossary/#production" class="glossary__link">production +<a href="{{ page.baseurl }}/docs/glossary/#production" class="glossary__link">production site</a>, you should know precisely what version you're running, and deploy Alaveteli from a [*specific* release tag](https://github.com/mysociety/alaveteli/releases). @@ -76,7 +76,7 @@ Patch version increases (e.g. 0.1.2.3 → 0.1.2.**4**) should not require any Minor version increases (e.g. 0.1.2.4 → 0.1.**3**.0) will usually require further action. You should read the [`CHANGES.md`](https://github.com/mysociety/alaveteli/blob/master/doc/CHANGES.md) document to see what's changed since your last deployment, paying special attention to anything in the "Upgrade notes" sections. Any upgrade may include new translations strings, that is, new or altered messages -to the user that need translating to your locale. You should visit <a href="{{ site.baseurl }}docs/glossary/#transifex" class="glossary__link">Transifex</a> +to the user that need translating to your locale. You should visit <a href="{{ page.baseurl }}/docs/glossary/#transifex" class="glossary__link">Transifex</a> and try to get your translation up to 100% on each new release. Failure to do so means that any new words added to the Alaveteli source code will appear in your website in English by default. If your translations didn't make it to the |