Legacy Content Migration

[jonaharagon]

No longer accurate information!

---

---

---

So, obviously we are starting our recommendations based on the recommendations currently provided on https://github.com/privacytools/privacytools.io. The codebase for this repo is actually 100%(ish) compatible with their repo, so as this is being developed we can continually merge in changes on their end as well. Obviously the end-goal of this migration is to stop doing this and operate this independently. But in the meantime, this allows us to merge in contributions on that side of things and retain commits/contributions to give credit to contributors there.

Recommended Software Platforms

On privacytools.io, lists of recommendations are bundled together as files in _includes. We've preserved this content in /_includes/legacy/sections/ but of course we want to move these out as we progress, into their own standalone pages.

How does that work?
Each category of software on Privacy Guides is a collection in the aptly named /collections/ folder. Each piece of software then becomes its own individual file in this hierarchy. These files can be either .md or .html files, preferably markdown but in certain cases we may need more advanced formatting.

Taking Tor Browser for example, we would create a file called /collections/_browsers/tor-browser.md, with the following content:

---
name: Tor Browser
type: Recommendation
info: Provides Anonymity
logo: /assets/img/browsers/tor-logo.svg
short: "**Tor Browser** is your choice if you need an extra layer of anonymity. It’s a modified version of Firefox ESR, which comes with pre-installed privacy add-ons, encryption, and an advanced proxy. [How does Tor work?](https://write.privacytools.io/my-thoughts-on-security/slicing-onions-part-1-myth-busting-tor)"
website: 'https://www.torproject.org/'
website_tor: 'http://expyuzz4wqqyqhjn.onion/'
privacy_policy: 'https://support.torproject.org/tbb/tbb-3/'
platform_win: 'https://www.torproject.org/download/'
platform_mac: 'https://www.torproject.org/download/'
platform_linux: 'https://www.torproject.org/download/'
platform_android: 'https://play.google.com/store/apps/details?id=org.torproject.torbrowser'
platform_fdroid: 'https://guardianproject.info/fdroid/'
source: 'https://trac.torproject.org/projects/tor'
order: 2
---
Tor Browser is your choice if you need an extra layer of anonymity. It's a modified version of Firefox ESR, which comes with pre-installed privacy add-ons, encryption, and an advanced proxy. [How does Tor work?](https://write.privacytools.io/my-thoughts-on-security/slicing-onions-part-1-myth-busting-tor)

{% include downloads.html %}

The YAML front matter between the --- lines is the most important part, and there are a variety of configurable options here:

• name (required)
• type (required): currently, this can be set to Recommendation, Worth Mentioning, or Anti-Recommendation
  • Yes, we want to include software that is not recommended, but this should not be an all-inclusive list
• info (optional): This is included as an informational badge on the card used to highlight key information. Multiple badges can be defined here, but the key is to keep it limited and keep them brief. Additional information can be included in the short or long descriptions later, of course.
• warning (optional): Similarly, this is included as a warning badge on the card, used to highlight key dangers. Again, multiple badges can be defined here, but very verbose texts should be reserved for the relevant descriptions later.
• logo (required): This is an absolute link to the logo of this project, which should be an svg, and should be square.
  • Some of these files already exist in /assets/img/legacy_*, and should be moved over to their respective category in /assets/img/ instead, creating a new folder if necessary.
• short (required): This is the short description of this project, and is what is included on the recommendation card. Markdown can be used here.
• website (required): This is the homepage of the project.
• website_tor (optional): This is an .onion link, which should be to the same page as the website above. TODO LibRedirect #1
• privacy_policy (optional): This is a direct link to the relevant privacy policy of the project. TODO Encrypted Doodle alternative #2
• platform_* (optional): These are direct links to downloads for various software platforms supported by the project.
  • Currently supported platforms:
    • platform_win
    • platform_mac
    • platform_linux
    • platform_android (google play specifically)
    • platform_ios
    • platform_bsd (not shown on recommendation card)
    • platform_fdroid (not shown on recommendation card)
  • Any other platforms can be added as necessary along this same format, but they will need to be added to downloads.html at a minimum.
• source (optional): This is a direct link to the canonical source code of the project.
• order (recommended for type: Recommendation, optional for other types): This is the order this recommendation should be presented on the site, defaults to alphabetical.
• seo (recommended): true/false - Whether a page should be indexed by search engines, defaults to true for type: Recommendation, false for other types. Not yet implemented, TODO Privacy Guides Forum #3.
  • Basic rule of thumb: This should be set to true if the page has a noteworthy long description (see below). If the long description page adds no value over the information already included on the recommendation card itself, set to false (or, add a more verbose long description! We're Privacy Guides and we want as much relevant information as possible for people to follow).

The rest of the page underneath the YAML front matter is the "long description" of the project. Long descriptions are required for type: Recommendation and optional for others.

This description is not shown on the recommendation card, but can contain all sorts of information that people would find useful. This can either be HTML formatted or Markdown formatted depending on the file type of this file. At a minimum this description should include some short description (even just a copy of the short description above if necessary) and a downloads section. See tor-browser.md for an example of a very brief description (seo should probably be false on this file...) and firefox.html for an example of a more substantial page.

Avoid empty descriptions (mainly for recommendations), which is why even adding the brief copy is preferable at this point, because it will be used to generate a page that is linked to by the recommendations card (the "More Information" button).

These descriptions will be useful for adding noteworthy information about a product, particularly regarding intended setup/installation, different use-cases, etc.

Eventually, these descriptions will function as essentially a "wiki" of information where we can collaboratively add information on different projects!

Category Pages

Pages that correspond to different categories on PrivacyTools that have not yet been migrated are located in the /legacy_pages/ directory in this repo. To convert the page to the new Privacy Guides format, we first want to move that page from /legacy_pages/ to /collections/_evergreen/.

Then, we want to make the following changes.

The YAML front matter should look like this, for example:

---
layout: evergreen
title: Browser Recommendations
description: "These are our current web browser recommendations, settings, and add-ons you can use to preserve your privacy."
---

• layout: should be evergreen currently
• title: name of the page/category (corresponds to existing title in legacy pages)
• description: a brief summary (corresponds to existing description in legacy pages)

Legacy pages may include additional attributes (permalinks in particular) that should be removed.

Next, any included sections should be copied over. Legacy pages used _includes for various sections, but we want all this content directly on this page. Recommendation cards should be implemented similarly to this:

{% assign browser = site.browsers | where:"name","Firefox" %}
{% for post in browser %}
{% include recommendation-card.html %}
{% endfor %}

{% assign browser = site.browsers | where:"name","Tor Browser" %}
{% for post in browser %}
{% include recommendation-card.html %}
{% endfor %}

(currently they have to be added once for every software, TODO a better system #4)

Sections that are not recommendation cards can be copied directly over. See the content on browsers.html as an example. Note that the fingerprinting section's HTML is directly on this page now.

Once everything exists on the new page, any sections it used can be deleted from /_includes/legacy/ as they are no longer used.

[dngray]

No longer relevant since privacyguides/privacyguides.org@8ef8e2a