TechDocs/Mainpage/Editing

This page has been moved to FSFE docs.

Working with the website source

Getting access to the web pages

The source files for the web pages are stored on the fsfe-website Git repository, hosted on the FSFE's Git service. Other services are also available on the related Git instance.

To have access to these tools, just follow these instructions:

To have write access to the Git repository just write to system-hackers@lists.fsfe.org

Working with Git

You should be familiar with Git, and you should have an account on git.fsfe.org. For documentation on how to use Git, you can check out TechDocs/Git. The workflow for working with fsfe-website is documented in TechDocs/Git/Workflow. Read it carefully. If you do not understand any of the steps, please ask a technically inclined person or the Web Team and ask them to improve the Wiki page afterwards, so that others will not run into the same problem again.

Enabling Git hooks

We strongly recommend to enable some security measurements in the form of Git hooks. These are scripts that are called on your computer, e.g. when making a commit. Currently, the following client-side checks are available:

To activate these checks, run this command from the root directory (i.e. first level) of the fsfe-website repository (or the fork you cloned):

ln -sr tools/githooks/* .git/hooks/

If you see an error that the hook files (pre-commit and pre-receive at the time of writing) already exist, please check whether they are the same as the ones in tools/githooks/. If not, please take care of merging them together.

Requirements for Git-Hooks: You need to install the packages: curl, mediainfo, and you need xmllint. Please note that you have to have the xmllint command available which is provided by installing the packages libxml2-utils (e.g. Debian) or libxml2 (e.g. Arch Linux, Fedora) on your computer.

If some file has a wrong syntax, it throws an error and you can fix the problem. This way you don't have to be afraid to break anything with your contributions.

Coordination tools

The work on the website pages is coordinated on the Webmasters mailing list.

In the fsfe-website repository's web interface you can find an issue tracker and the commit log.

The web team's wiki page may contain some further information about the webmasters' workflow.

If you want to keep track with all commits that are done to the web page sources, you can also subscribe to the commit notification mailing list and you will get a mail for every change posted to the source tree.

Responsible handling of write access

If you have write access to the web pages, please subscribe to the Webmasters mailing list.

Please bear in mind that all your changes will become effective and visible automatically, without any further action of anybody. Consequently, there are a few things we would request you to do whenever you commit changes or new files:

Please coordinate with other people who also have Git write access to make sure that translations and fixes contributed by people without commit access are committed properly after they have been proofread. Of course, please check these files before you push them like you check your own files.

Advanced information

Read-only access

If you don't have an account on git.fsfe.org and just want to have a copy of the websites' sources on your computer, or if you cannot use the SSH link for any reason, you can also clone via the HTTPS clone link:

git clone https://git.fsfe.org/FSFE/fsfe-website.git

But if you want to edit the website source we encourage you to use the SSH clone link starting with git@git.fsfe.org. Otherwise you will have to type in your Fellowship account credentials every time you push a change.

The test branch

The Git repository has two main code bases for the FSFE website, the master, which is used to build the production instance of the website at fsfe.org, and the test branch, which is used to build test.fsfe.org.

To work on major changes to the website, including debugging new features that could potentially break the site, you are encouraged to check out the test branch of the Git repository: git checkout test

In order to make changes to the test page, make them inside the test branch and push them to is upstream location:

git push upstream test

Checking out Pull Requests

For some reasons, e.g. previewing someone else's changes locally, you can check out Git Pull Requests.

To enable this, you will have to tell your git to fetch remote pull requests. Please open a terminal and navigate to the fsfe-website repository on your computer. Now type or copy/paste:

git config --add remote.upstream.fetch "+refs/pull/*/head:refs/remotes/upstream/pr/*"

The above command adds another reference your git asks for information from the upstream remote. It translates this location to a branch you can work with.

Afterwards, you can enter any existing pull request of this repository just like a branch. For example, Pull Request #42 can be checked out with:

git fetch upstream
git checkout upstream/pr/42

Please note that you cannot make edits in the pull request this way, so a push is not possible. If you would like to work together as a team on a shared branch, there are other ways. Please ask the web@ mailing list for instructions.

Including fixed and variable text modules

We have defined a number of text modules that you can include within the <body> element as you see fit.

Fixed text modules

Fixed text modules are prefabricated blocks of HTML code defined in the directory global/data/modules. You can use them in any page you like.

For example, to include the module defined in the file global/data/modules/banner-subscribe.en.xml (or its counterparts for other languages), just include the line

<module id="banner-subscribe"/>

wherever you want that content to appear.

Variable text modules

Variable text modules are compiled from information available in small XML files. For the page pagename.xx.xhtml, the file pagename.sources in the same directory defines which XML files to use.

To include a verbose list of news and events matching a specific topic, follow these steps:

  1. Decide about the tag key you want to use to select the news and events to include. Let's say it's "mytag".
  2. Add the following to the .sources file:

    news/*/*:[mytag]
    news/*/.*:[mytag]
    events/*/*:[mytag]
    events/*/.*:[mytag]
  3. Include the line

    <related-feed tag="mytag"/>

    wherever you want the news and events to appear. News and events will both be preceded with a <h2> heading, so make sure that this fits your hierarchy of headings.

To include a compressed list of news and events matching a specific topic (suitable for a sidebar), follow these steps:

  1. Decide about the tag key you want to use to select the news and events to include. Let's say it's "mytag".
  2. Add the following to the .sources file:

    news/*/*:[mytag]
    news/*/.*:[mytag]
    events/*/*:[mytag]
    events/*/.*:[mytag]
  3. Include the line

    <related-list tag="mytag"/>

    wherever you want the news and events to appear. News and events will both be preceded with a <h3> heading, so make sure that this fits your hierarchy of headings.

Uploading pictures

Many image files are spread throughout the whole website repository: icons, graphics, logos in all sizes. This is fine for context-related files, e.g. an icon specifically used for one page, or the pictures of merchandised displayed in the shop.

However, this is different for pictures that can be used in news articles, newsletters and so on. Because we would like to preserve the original size for the graphics we use, in case we need them again, but of course also want to use a smaller size for inclusion in the online page, and because we do not want to use up too much space in the version control system, we opted for using an external image hosting service that is specialised for maintaining albums, tags, and searching through the whole picturebase.

The service we use is called Lychee and resides on pics.fsfe.org. You need to log in to be able to use it. If you are an editor who needs to upload files, contact the Web team. FSFE Core Team members can visit the more detailed, internal documentation about the picturebase.

Images used in articles on the webpage must have an aspect ratio of 16:9. This will be checked when the article is committed to the repository. If you are correcting or updating an old article that includes images not in the correct aspect ratio, these images need to be corrected and re-uploaded to the picturebase. If you are an editor and don't have access to the picturebase, please contact the Web team. Once the image is corrected, you can use the it in the article.

Adding meta information

In our XHTML files, you can set some invisible information which affects how fsfe.org and individual sub-sites appear for search engines and on social networks. It can also set some other parts of the website, e.g. for a link to the discussion/comments forum or the tags. All of this is included *outside* of the <body> element – ideally after </body> but before </html>!

Description

For preview cards on social media, forums, search engines etc, we usually use the first paragraph as an extract text. However, if that does not fit, or if you wish to modify it, you can set a description manually:

<description>Show your love for Free Software by using and wearing the branded items the FSFE offers.</description>

Please make sure to limit it to ~160 characters, but keep it verbose and informative at the same time.

You can check the source code of the built website in your browser, or paste the URL in opengraphcheck.com to verify that everything works.

Preview Image

When a link to a website on fsfe.org is shared on a social network or any other site supporting this feature, one can see a small preview image and text. For the text, the above "description" element is used, or alternatively the first paragraph if the former is not existent.

You can also configure the image. Per default, the FSFE logo is being used. But with adding the following element, you can change it. Please note that you should always use an absolute URL, and it should start with https://fsfe.org/ and not be an external URL. For example, on /order/order.en.xhtml it looks like the following:

<image url="https://fsfe.org/graphics/tshirt-promo-800px.jpg" />

For news/newsletters/podcasts, the image must be in the 16:9 format! Please take care that it is not wider than 1200px, and not larger than 500 KB.

Authors

You can display the authors of a news items or articles on fsfe.org with the <author> tag. For example, this page lists multiple authors. Here is an excerpt of how this tag is used, again after the </body> and before </html>:

<author id="albers" />
<author>
  <name>Fernando Sanjurjo</name>
</author>

If the person is a FSFE team member, one can use the ID of a person (usually the surname). This takes the full name of a person, the avatar and a link from the people.en.xml file. You can also set a name manually, e.g. if the person is external from the FSFE.

In the example, "albers" is Erik Albers from the FSFE, and Fernando Sanjuro is manually set.

Translator

Translators do a tremendous job to make fsfe.org accessible for as many people as possible. That is why we encourage them to claim credit for their work. Any translator can add the <translator> tag in their works. For example in /news/2019/news-20190124-01.nl.html, André did it like this in line 66:

<translator>André Ockers</translator>

The result is visible on the final website in the footer section, in this example here. If there are multiple translators, just separate them with the equivalent of "and" in your language, or just commas.

Download

If you would like to provide a link to a downloadable resource, e.g. downloading a white paper in PDF form, you can do this via the <download> tag. On this page, we offer a PDF download in this form:

<download type="pdf" content="https://fsfe.org/activities/policy/eu/20170105-horizon2020-position-paper.pdf" />

The value of type just sets the text of the link. "content" sets the actual link to the downloadable resource.

Tags

On fsfe.org, you can tag news and event items. You can use it like the following, taken from this page:

<tags>
  <tag key="front-page"/>
  <tag key="pmpc">Public Money Public Code</tag>
  <tag key="policy">Policy</tag>
  <tag key="procurement">Public procurement</tag>
  <tag key="europeanparliament">European Parliament</tag>
  <tag key="publicadministration">Public Administration</tag>
</tags>

Each tag is in a separate <tag>, and all tags altogether are capsuled within the <tags> tag.

The text after key=" of each tag is the internally unique tag, while the text between the > and < is the visible text of this tag on the website. Please do not introduce new tags without checking back with the web team. You can find existing tags on this page, but please note not to copy the descriptive text but the text between "" in the headline of the respective tag page.

Comments

For news, newsletters, or podcasts you can link to a discussion topic on our Discourse instance. This way, interested minds can elaborate and exchange there. The link will be displayed below the article. An example is available in this news item.

In the XHTML file, please add after the closing </body> and before the closing </html>:

<discussion href="https://community.fsfe.org/t/test-news-item-for-testing-purposes/231" />

Regarding the procedure for that, we recommend following steps:

  1. Log in to the Discourse news manager with your FSFE account (more info here)

  2. Add a new topic with the title and teaser of your news item, and the language-independent link it will have
  3. Copy the link and add it into the <discussion tag

  4. As soon as your news item is published, also publish the topic in the online service

Licensing

Licensing your source code

Whenever you introduce either server side program code (i.e. PHP, Perl) or JavaScript code to the website, please make sure you comply with our licensing policies. Specifically this means:

Use custom licensed media

If you use images or other media which which has been licensed using a Creative Commons license or another license, you can make sure that the proper licensing information is displayed by adding these at the end of the document before </html>. Here are three examples:

<legal type="cc-license">
  <license>https://creativecommons.org/licenses/by-sa/3.0/</license>
  <notice>This work is published under the Creative Commons BY-SA 3.0 Unported license by John Doe</notice>
</legal>

<legal>
  <license>http://www.gnu.org/licenses/fdl-1.3.txt</license>
  <notice>This page is published under the GNU Free Documentation License 1.3 or later</notice>
</legal>

<legal>
  <notice>This work is published under the CC-BY-SA 3.0 Unported license or the <a href="http://artlibre.org/">Licence Art Libre 1.3</a> at your option, etc.</notice>
</legal>

TechDocs/Mainpage/Editing (last edited 2023-09-14 13:40:16 by irakli)