diff options
Diffstat (limited to 'docs/customising')
| -rw-r--r-- | docs/customising/config.md | 26 | ||||
| -rw-r--r-- | docs/customising/index.md | 10 | ||||
| -rw-r--r-- | docs/customising/states.md | 8 | ||||
| -rw-r--r-- | docs/customising/states_informatazyrtare.md | 18 | ||||
| -rw-r--r-- | docs/customising/themes.md | 52 | ||||
| -rw-r--r-- | docs/customising/translation.md | 20 |
6 files changed, 67 insertions, 67 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, |