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 toimage_url
in bedrock since bedrock knows the real static URL. Same forinclude_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 totitle
. You may need to providega_title
in situations where thetitle
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 withhttps://
) or a URL name in bedrock that will be converted to a URL using Django'sreverse()
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:
- 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.
- 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.
- Process the YAML and Markdown in the data files and output
.json
files that are easier to load by bedrock. - Upload the static files to the s3 bucket for whichever site instance will be needed.
master
branch changes go to stage, andprod
branch changes go to prod. - Commit the changed images and new
.json
files to a newmaster-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: