Content Cards Admin

This repo contains data and image files that control the content for various parts of some pages on instances of Bedrock (e.g. www.mozilla.org). The data files are Markdown with YAML front matter similar to those of popular static site/blog generators like Hugo and Jekyll.

Directory Structure

The directory layout and file names have meaning:

content/                       # folder for all of the data
    home/                      # one folder per bedrock page
        card_1/                # one folder per card
            en-US.md           # card named "card_1" in "en-US" locale
            de.md              # same card but in "de" locale
            fancy.png          # image referenced as "image: fancy.png" in .md file(s)
            fancy-high-res.png # image required if "include_highres_image: true" in .md file(s)
        the_dude/
            en-US.md           # card named "the_dude" in "en-US"
            abide.jpg          # image referenced from "image: abide.jpg" in .md file

The home directory under content above is important, because it is the name by which you'll refer to all of the cards for that page when you fetch them in a bedrock view. The next folder down (e.g. card_1) is also important as that's the name you'll use in your template where you'd like to output that card. See the bedrock docs on this for more details.

Data File Structure

The data in each file can really be any YAML you want. For the home cards the data names are basically the argument names for the card() macro in bedrock. This allows for more flexibility in that you can specify any argument for that macro in your data if you need to. Some data is specially handeled however:

  • image is processed in this repo and converted to image_url in bedrock since bedrock knows the real static URL. Same for include_highres_image. These values should be relative to the card's folder and the file(s) will be checked to make sure it exists.
  • If you don't provide a ga_title it will be set to title. You may need to provide ga_title in situations where the title is in a different language than you'd like the GA data.
  • media_icon should just be the short name, e.g. "video" or "audio" and will be converted to the full protocol class value by bedrock.
  • size should also be the short name "small", "medium", "large", "extra-small". If omitted "small" is the default.
  • Similar to the above 2 aspect_ratio should be set to simply "1-1" or "16-9" etc.
  • link_url can be either a full URL (starting with https://) or a URL name in bedrock that will be converted to a URL using Django's reverse() function. Be careful using this as changes to a URL name in bedrock or a miss-spelling here can cause pages to error.

Here is an example file.

---
# content/home/card_1/en-US.md
title: "We keep your data safe, never sold."
# content/home/card_1/ffyr.png
image: "ffyr.png"
link_url: "firefox.fights-for-you"
tag_label: "Video"
size: "large"
aspect_ratio: "16-9"
include_highres_image: true
desc: "You have the right to your own life — and your own data. Everything we make and do fights for you."
youtube_id: "rZAQ6vgt8nE"
media_icon: "video"
---

If there was markdown content it would go *here*.

We aren't currently using the Markdown content for the home page data, but it does work and is synced to the bedrock database for future use. Also note that any unicode character should work (emoji included).

Local Validation

If you'd like to check processing locally before pusing to the main repo and waiting for CI, you may run the following command:

$ docker-compose run app

If it completes successfully you can see the results in an output directory. If anything is wrong with YAML or image processing the command will fail with an error message.

Deployment Process

In order to get your changes onto dev you should push to the dev branch. You can do this before any pull-request or code review happens in order to get content review by the requesting team. Once that is tweaked and approved you should open a pull-request from dev (or whatever branch you want really) to master for code-review from a teammate. This pull-request isn't required as successful deployment and content approval is all that is really needed for review, but if you would like extra review then this is the time to do it.

Once a change to these files is merged to the master (or dev or prod) branch a process in our CI does several things:

  1. Calculates the md5 hash of the image file contents and adds that hash to the file name. This is similar to what Bedrock does to other static media and is what is called an "immutable file" for caching, since any change to the file will result in a different file name. This allows us to set the maximum cache expire times.
  2. Check to make sure that every image file (including high-res) referenced in a data file exists in the card directory and has been processed.
  3. Process the YAML and Markdown in the data files and output .json files that are easier to load by bedrock.
  4. Upload the static files to the s3 bucket for whichever site instance will be needed. master branch changes go to stage, and prod branch changes go to prod.
  5. Commit the changed images and new .json files to a new master-processed branch and push that to the repo.

Bedrock itself will load the files from these {dev,master,prod}-processed branches (depending on which bedrock it is). You should see notifications of the CI process in the #www-notify channel on Slack.

Once again, to be clear, the branch to bedrock instance mapping is as follows: