Max Mehl
Hugo RoyIndustry Committee vote: Technology sovereignty is only possible with Free Software
Industry committee of the European Parliament shows necessity and benefits of “open-source first” policy but report lacks concrete measures.
Overview of website features
This page shows various features that the fsfe.org website provides for
editors. It is far from complete and always work in progress, just like
the website in general. And hey, already this paragraph is a special
feature, the <div id="introduction">.
Table of contents
If you would like to follow how the features are actually being used, make sure to have a look at the source code of this page. You will find a link in the footer, as on every page.
First of all, when editing or creating websites, please make sure to enable the Git hooks and follow the best practices. They will mitigate a lot of common issues and make things more pleasant for you and others.
Secondly, be aware that not all features work on all pages. News items and
events have some limitations or extra features. Some things are only
possible when you have set <body class="article"> (like
the sidebar), while <body class="overview"> is a
full-width page with other benefits.
Thirdly, also be aware of the more technical documentation of the features on the Editing wiki page. While the page you are currently looking at is rather meant for editors, the wiki page may be more helpful for our tech-savvy web developers.
Meta data
You can add various meta data and clever tags in your XHTML file. This wiki page shows all of them. In this article, we set multiple authors (see on top) and a description and image that are visible in social media and other pages.
Links
Linking to websites using <a href="https://example.com">click
me</a> is the 101 of HTML. However, there are a few neat
tricks you should know of.
Anchor links
You can not only link to separate website, but also to parts of your page. This can be done with anchor links. To achieve this, you'll first need to mark the portion of the website that you would like to link to. In most cases, this should be done by marking a headline. A use-case could be a table of contents.
In this example, we gave the headline above this section ("Anchor links")
an id: <h3 id="anchor-links">Anchor links</h3>.
From now on, we can link to the id "anchor-links".
If you want to link to a section of the same site, you need to
prepend the link with a "#". So this link is
just href="#anchor-links". However, you can also from another
site link to this specific section. Such a link could look like this:
<a
href="https://fsfe.org/contribute/web/features.html#anchor-links">click
me</a>.
NOTE: if you do not add an id attribute to
headlines, our build system will automatically do so, starting with
id- and then followed with the name of the headline (and some
modification). However, you are discouraged from using this effectively,
because this id will not be the same if the article is translated. So if
you link to a headline having the content "Important Section" via the
automatically generated anchor link #id-important-section,
this link will not work in the Italian translation where the automatically
generated id of the headline will be id-sezione-importante or
so.
Donation links
A special feature of our website is the automatic setting of a donation link. Let's say you write a news item and would like to motivate people to become supporters or make a one-time donation. You could just directly link to the donation page, but ideally you want to learn which article motivated people to contribute.
For this, you can just use fsfe-cd-donate-link. Instead of
doing <a href="https://my.fsfe.org/donate">help
us</a>, you can do: <fsfe-cd-donate-link>help
us</fsfe-cd-donate-link>. This automatically sets a referrer
to the donation link. The even cooler thing: it also works with buttons or
anything else that you do with a tags:
To learn more about buttons, click here.
Emails
It is common to include email addresses in your text, e.g. if your would like to get direct feedback on a topic. Unfortunately, this will make the posted email address likely to receive a lot of spam because bots are crawling all kinds of websites to get email addresses they could spam.
Our system supports some basic ways how to prevent that and still be
accessible to people using a screen reader. To just show an email address
safely (like donotmailme@fsfe.org), do it like
<email>donotmailme@fsfe.org</email>. If you want
that people can just click on the link to have their email application
opened with the mail as recipient (like donotmailme@fsfe.org), make it <email
mailto="yes">donotmailme@fsfe.org</email>.
Graphics
Including nice graphics is one of the most important steps to make a page attractive to readers. Therefore, we support many ways how to embed graphics, position them neatly, and fit them to your content. Let's have a look at the default way how to include a picture: (almost) full-size, shadow around it, and a caption below:
The code for that would be the following (the next examples won't have this explicit code display, so have a look at the source code then):
<figure>
<img src="/graphics/group-blur-800.jpg" alt="A random group picture" />
<figcaption>
A picture of a group, somewhen in 2013
</figcaption>
</figure>
You can equip the <figure> element with many more
classes to adapt them to your needs. Here are some examples:
On the right, we have a class="float-right", and this time
without a figcaption. On large screens, it will stick to the
right, on small ones it will become full-width to stay visible for
visitors. Of course, float-left is also possible. We have
also wrapped the image in a link (using the a element), so
people can click on it. Links should be used wisely as they direct your
readers away from the current page.
You can also control the width of the image freely. Add the
max-width-XX class to the figure, where XX equals a number
between 0 and 100 in steps of 5. In the example below, we set it to 55,
and apply a few other classes:
Did you notice that the shadow around the picture is gone?
no-border sets that. And for some reason, we defined that the
text in the figcaption shall be aligned to the right, by applying the
text-right class.
BE AWARE: although we have all these classes, please don't overuse them. We strive to keep a more or less uniform style on fsfe.org. Therefore, try to be consistent with other, similar pages, and don't make your page a playground for wild styling experiments.
Videos
Videos work similarly to graphics, but are a bit
more complex. As graphics, they should be wrapped inside a
<figure> element and can use the same classes for
sizing, shadows, or alignment. However, a video has to come in two
different formats for best software freedom support (Webm) and
compatibility (MP4), and in different resolutions for bandwidth saving.
Our primary video platform is our Peertube instance. You should
upload/import the video there first, or ask the responsible person for
this. This video is then available via a link, e.g.
https://media.fsfe.org/w/kGvs3JNADvvQfkC1dR9FGr.
Unfortunately, we currently cannot directly embed the video from Peertube directly. Therefore, we provide the Peertube Embedder, a script on our download server that automates the necessary processes of download and conversion. Please follow the tool's documentation to learn how to use it and how it works. There you will also find a list of drawbacks of this temporary solution.
If this is finished, you will receive a tag like the following:
<peertube url="https://media.fsfe.org/w/kGvs3JNADvvQfkC1dR9FGr"
/> that is internally translated into the video. Wrap this in a
figure, and optionally extend it with a caption and a link to the original
video:
Quotes
For many pages it may make sense to add quotes in between a wall of text. Also here, the FSFE website provides a number of options: raw text, or enriched by a picture, the quoted person's name etc:
This is a standard quote. Remember that you'll still have to wrap paragraphs in their respective
<p>.
Let's add the author of a quote nicely by adding
<cite>:
"The problem with internet quotes is that you cannot always depend on their accuracy."
Abraham Lincoln
To increase authenticity even more, let's add a picture next to the quote:
"Finally I am free! Thanks to the FSFE's 'Free Your Android' and 'Upcycling Android' campaigns, I learnt how to break free from proprietary dependencies! I recommend every android and human to do the same."
A. Droid, random mobile phone
Another example with different mixture of classes. We apply
small-img to the with-image-right div that, as
the name says, puts the image to the right instead of the left. We also
use the class img-circle on Matthias' picture. Note that for
this, the picture must be square!
"We are happy to see that the good energy and resources the FSFE community dedicates on creating, translating and promoting the campaign's objectives keeps increasing support from major public stakeholders."
Matthias Kirschner
Interviews
We sometimes publish interviews, for example with an interesting person. Sometimes, we also ask the same questions to multiple political parties, and want to list their answers using the party colours. Find out how this works:
FSFE: What are the freedoms of Free Software?
Jane Doe: These are the freedoms to use, study, share, and improve software.
I write this in a second paragraph on the same level: They safeguard user rights!
What is the answer to all questions?
I assume it's 42.
FSFE: Are you sure? Isn't it 23?
Oh, well, I don't know.
Thank you for your time.
Likewise.
If you look at the source code, you will see that we sometimes use
<p class="question"> and sometimes <div
class="answer"> with multiple <p> inside. If
a question or answer contains multiple paragraphs, wrap them in a
<div> with this class, but leave the <p>s without any class.
If they are only one paragraph, it's suffient to just use a <p> with
the respective class.
Party questions (like Ask Your Candidates)
For parties, we have some predefined coloured boxes. You will find them in
the file /look/elements/interview-ayc.less. Here is a snapshot.
What is your favourite colour?
Leaf Party: Obviously green and every variation of it.
Sun Party: Red as the sun that keeps us all warm.
Did you know that red has the colour code #FF0000?
Sky Party: Blue, because it makes us calm and is pretty to look at.
Tables of contents
If you have a long page, adding a table of contents may come in handy. We
offer a few options here. The default one is using a div with the class
toc. Inside, the first p element is the headline, and then
followed by a list, either ordered or unordered. If you choose ordered,
our system will automatically number the items accordingly.
You can link the different points to specific points of your page. Ideally, you do this via anchor links that you define manually for headlines.
You can also introduce a hierarchy of list items. For this, start a new ordered list ("ol") or unordered list ("ul") within a list item ("li") on the parent level. Below, you can find two non-functional examples: one with ordered lists (numbers), one with unordered lists (bullet points) on the first level, and numbered on the second.
Numbered contents
- First item
- Second item on first level, from here on without links
- First item on second level
- Third item on first level
Bullet and numbered points mixed
- First item
- Second item on first level, from here on without links
- First item on second level
- Third item on first level
- We can even mix ordered and unordered lists!
- OK, now it's getting silly...
- We can even mix ordered and unordered lists!
If you don't want the table of contents to use up the full width, you can
also move it to the left or right of the page. On the very top of this
page you can find and example for a table of contents being on the right
side, which is done by adding the class float-right to the
ToC's div element. float-left would do the opposite.
Sidebar
Depending on the class of the <body> element, you page
automatically has an empty space to the right (at least on larger
screens). This is the sidebar which is defined below the closing
</body>.
You can leave it empty (so just
<sidebar></sidebar>), then the build system put
some standard text there. But you can also use it for custom content. In
this example, we put a headline with "Sidebar content" followed by a few
links, related news, and a paragraph. Below,
there is a text motivating to support the FSFE, activated by adding the
attribute promo="support".
All available sidebar promos can be seen in
/build/xslt/fsfe_sidebar.xsl. Currently, these are
our-work, support, donate or
none. Ask the web team if you miss something!
Modules
There are pre-defined modules that you can include almost everywhere on fsfe.org. This way, translators don't have to translate the same text over and over again, and such things can be improved centrally. For instance, check this out:
You can find all modules here, and can add new ones. However, if you are not very familiar with the FSFE website, please consider asking the web mailing list or someone from this team first.
Small pitfall: if you build the
website locally and include a module in a page for the first time,
you'll have to run make after including a module once.
Footnotes
Especially for studies and longer articles, you may want to use footnotes. This is simple to achieve once you understand the basic principle.
In this paragraph, we'll add two footnotes. One is here, and let's put another one behind
here. The cool thing:
you don't have to set the numbers yourself! However, it's critical that
you retain role="doc-noteref" for each of them, and
role="doc-backlink" for the backlinks below.
Normally, you would have the actual footnotes at the end of the page, so
just before </body>, but let's put it next to this
paragraph.
Footnotes
-
We called this footnote
fn-1and the backlinkref-1but that's completely up to you. -
Most importantly, it should be consistent across the page so you don't
get confused by the
fn-numberandref-number.
Structuring content
By default, if you just enter text in <p> elements, you
just create a wall of text. Sometimes it makes sense to split the page, or
otherwise organise information in smaller pieces. Here are some examples
of what you can do:
50-50 grid
With <div class="grid-50-50"> and the follow-up divs
you can create two or more boxes besides each other. On smaller screens,
they will be below each other, allowing for enough space. The boxes can
contain text, pictures, or videos. Just make sure that the boxes are
somewhat equal in height to give it a good look.
This is how the law is currently drafted:
- You shall not use software for every purpose
- You shall not be able to study technology
- You must not share software with friends
- By no means you must be able to improve technology
This is what the FSFE proposes instead:
- You have the freedom to use software for any purpose
- You have the freedom to study software
- You have the freedom to shate software with everyone
- You have the freedom to improve the software
Icon grid
Instead of a mere 50/50 box, you may want to add icons to smaller points you are making. Here, we offer a neat icon grid with exciting options. Let's check out the basic version:
-
Autonomy
Free Software helps to develop and maintain tailored software that suits your needs, not just the vendor's business model.
-
Collaboration
Free Software can be shared and used in a non-exclusive way by everyone – serving the public good.
-
Share & Copy
A Free Software licence allows a limitless number of installations to be run, without paying extra.
-
No Lock-in
Free Software licences reinforce independence from vendors and provide more choice in service providers.
Some extra classes can refine the whole look and make it very flexible. We
will look at icons-sm, one-per-row,
no-icons, and icons-middle in short examples.
-
Use
Free Software can be used for any purpose.
-
Study
Free Software and its code can be studied by anyone.
-
Autonomy
Free Software helps to develop and maintain tailored software that suits your needs, not just the vendor's business model. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim.
-
Collaboration
Free Software can be shared and used in a non-exclusive way by everyone – serving the public good. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. Integer tincidunt. Cras dapibus. Vivamus elementum semper nisi. Aenean vulputate eleifend tellus.
Related content via tags
On campaign websites you may want to automatically include the latest news
about your activity. This works on the basis of tags. Each news item
should carry tags. The currently existing tags are listed here. What's important is the tag's
key
For example, the tags section of this news items looks like the following:
<tags>
<tag key="front-page"/>
<tag key="internal">FSFE Internal</tag>
<tag key="tech-teams">Technical Teams</tag>
</tags>Now, we want to include news about the technical teams of the FSFE below this paragraph, and also in the sidebar. This looks like the following:
In order to make this work, you need to create a file next to the XHTML
file you are creating anyway. In the case of this page, whose file is
called features.en.xhtml, you'll need to create
features.sources. In this
file, you define the files that the build system shall look for as
candidates for inclusion. The content of this article's sources file is:
news/*/*:[tech-teams]
news/*/.*:[tech-teams]
events/*/*:[tech-teams]
events/*/.*:[tech-teams]
It asks the build system to have a look at all news items and events that
contain the tag tech-teams. But the system will the only
regard news items that have already been released (date older than today),
and event entries that are upcoming or currently ongoing, not past ones.
Variation: for the sidebar we've chosen
<related-list tag="tech-teams" count="2" /> instead of
related-feed. This does two extra things: the list does not
feature the latest news/event but is a plain list of entries. And with the
count attribute we overwrite the default value of maximum 5
entries and limit the list to the two most recent news/events.
By the way: if you don't want to display news items, just delete the lines
starting with "news/" - and vice versa for events - from the
.sources files.
Buttons
A very simple but powerful element is buttons. There are countless options
so we just mention the most used ones. In general, a button in our website
is nothing more than a <a> element with a few extra
classes.
Default button Button with the primary color Large green button Extra-small red button Orange button with link to this section
For more, you can check out the corresponding section on our Bootstrap version's documentation.
Coloured boxes
Sometimes, you may want to put some content within coloured frames, or
have an element that has a unicolour background. Here are a few options,
and all of them involve at least the class color-box.
However, please do not overload your page.
This box is using the class="color-box border" and
data-color="fsfe-blue".
The colours for data-color are defined in the file
/look/elements/color-box.less. Here is a link to a snapshotted
version.
This box is using the class="color-box background" and
data-color="android-lime".
This box is using the class="color-box background rounded" and
data-color="android-blue".
You can also stretch the box. A fullwidth box looks best on a
body class="toplevel" or body class="overview",
so page formats that do not have a sidebar.
This box is using the class="color-box background fullwidth" and
data-color="dark-green".
Conclusion
Phew, that was a ride! This article is far from perfect or complete. So if you need more info or wish to have another design option, please propose it to the Web team!