Website Production Library (wip)
Raw migration from word doc to be cleaned up
Introduction
This document defines the folder structure and naming conventions for the Website Production Library, a set of files used to produce pages and briefings.
The vBriefings framework depends on these conventions to maintain consistency, reliability, and long-term maintainability across all content and workflows. Following them ensures files remain predictable, searchable, and usable by collaborators and automation tools.
This document governs organization and naming only. It does not describe the production or editing of pages, briefings, or media, although related guidance may appear incidentally. Those topics are covered in separate documentation.
To understand the structure, review the existing briefings and pages as you read this document. The veganism and hunger briefings provide representative examples of nearly all subfolders described here.
Tech Note: In WordPress, a briefing is added as a post, and a page is added as a page. Sometimes “post” refers to any entry in WordPress terminology.
Slugs
What is a Slug?
A slug is the final segment of a URL (e.g., vbriefings.org/veganism). The slug serves as the stable identifier for a briefing or page and is used in folder and file names throughout the system.
The slug is often used to reference a specific briefing or page, such as the hunger briefing or the about page.
Slug Naming
Slugs should consist of a single word whenever possible. If a single word would create ambiguity or conflict, two words may be used. Multiple words should be separated by a dash (-).
Some topics represent closely related concepts that must be distinguished from one another. In these cases, a multi-word slug clarifies the specific topic (e.g., pig-sentience and pig-injustices identify different briefings within the same subject area).
Examples:
vbriefings.org/hunger
vbriefings.org/environment
vbriefings.org/about
vbriefings.org/pig-sentience
vbriefings.org/pig-injustices
vbriefings.org/cow-sentience
vbriefings.org/cow-injustices
Single-word slugs are preferred because the URL containing the slug is displayed prominently in social images and other materials to encourage direct access by frequent users.
Folder and File Naming Conventions
Folder names use Title Case with words separated by spaces. If a folder name contains a slug, the slug remains lowercase while all other words remain Title Case. The slug should be the only lowercase word in a folder name.
Examples
Briefings
hunger Briefing
about Page
Flashcards
Fact Check
File names follow a different convention. If a filename contains a slug, it should use lowercase words separated by dashes.
Examples:
hunger-briefing-featured-image.jpg
veganism-briefing-social-image.pptx
Filenames that do not include a slug may use spaces and normal capitalization, as they are typically copied into an asset folder and are not part of the structured naming system. Renaming them provides no organizational benefit and may make the original source harder to identify.
Example:
History of Veganism.pdf
Grazing Is Not Sustainable.pdf
In summary:
- folder names → Title Case with spaces (slug lowercase)
- filenames containing a slug → lowercase with dashes
- filenames without a slug → normal spacing and capitalization
Overall Folder Structure
Special Folders and Files
The following are defined special cases that may appear at multiple levels of the structure.
Read Me and Archive Folders
Some folder names begin with “aa” or “zz” to control ordering in a list of folders—folder names beginning with “aa” appear first and folder names beginning with “zz” appear last.
Examples:
aa Read Me First
zz Archive
aa folders should contain important reference or orientation material for that level (e.g., aa Read Me First).
zz Archive should contain material no longer in use but retained temporarily. Archived items should be reviewed and culled periodically.
Assets Folders
Assets folders contain source or application files used to produce another file (e.g., project files used to create an image, slide, or video).
Draft Files
[slug]-briefing-draft.docx or [slug]-page-draft.docx are Microsoft Word documents that are used to write and edit the text of a briefing before it reaches WordPress. It may be collaborative and worked on here until it is near completion.
Examples:
rodeo-briefing-draft.docx
about-page-draft.docx
When the page or briefing is published, the draft file should be moved into the Research folder.
Too Much Structure?
As you read this document, you may wonder whether we are imposing unnecessary structure. For example, an image or video file may be the only file at a given level and may have no assets collected in its production that need saving. Requiring a separate Assets folder for assets used in video or image production and requiring that Videos and Visuals each have their own folder may seem superfluous.
But if a second video is added for a briefing or page, or if future edits require adding video or image assets, you have the structure in place to handle it without rearranging the structure. It also simplifies this documentation, as there would be no need for statements such as “if there is only one video for a page or briefing…”
Top Level Folders
Within the Website Production Library Folder are four subfolders:
Website Production Library
—Drafts
—Pages
—Briefings
—PreDrafts
The PreDrafts folder is for potential briefings and pages that are still in the research stage and have not been published in WordPress as drafts. When it is entered into WordPress as a draft, a Briefing or Page is moved into the Drafts folder. Then, when published, it is moved to the Briefings or Pages folder, as appropriate.
Page and Briefing Folders
Under the top-level folders, there is one folder for each page or briefing, as shown below. The second-level folder contains the resources for pages and briefings. The lower-case slug is always the first word in the folder name, and either Page or Briefing is the second word. As you can see, the Drafts and PreDrafts folder can hold both Pages and Briefings subfolders, but the Briefings and Pages subfolders can only contain either Briefings or Pages, respectively.
Website Production Library
—Briefings
——veganism Briefing
——protein Briefing
—Drafts
——grazing Briefing
——donation Page
—Pages
——about Page
——privacy Page
—Predrafts
——rodeo Briefing
——team Page
Working Folders
Specific subfolders, known as working folders, are created under each second-level folder, depending on whether the item is a page or a briefing, and whether the briefing or page actually has the indicated asset. For example, for a briefing without slides, there would be no Slides folder. Briefings will always have a “Featured and Social Images” folder before publication and a Fact Check folder at or shortly after Publication.
No other folder names other than the ones listed below should be found immediately under each briefing, except as explained in “Special Files and Folders” above.
The allowable working subfolder names are Fact Check, Featured and Social Images, Flashcards, Future Edits, Research, Slides, Videos and Visuals, and zz Archive. These are shown in context below.
Website Production Library
—Briefings
——aa Read Me First
———folder-structure-and-naming-conventions-v4.docx
——veganism Briefing
———Fact Check
———Featured and Social Images
———Flashcards
———Future Edits
———Research
———Slides
———Videos
———Visuals
———zz Archive
——protein Briefing
———Fact Check
———Featured and Social Images
—Drafts
——grazing Briefing
———grazing-briefing-draft.docx
———Research
———Visuals
—Pages
——about Page
———Visuals
——privacy Page
———Visuals
—PreDrafts
——rodeo Briefing
———rodeo-briefing-draft.docx
———Research
———Visuals
Working Folder Descriptions
Fact Check Folder
This folder is for briefings only. It will be empty if no fact-checks have been performed, but an initial fact-check should be completed before or shortly after publication. Inside this folder will be an initial fact check document and any update fact check documents covering subsequent edits. There may also be supporting verification documents as discussed below. Here is an example illustrating the pattern to follow. In this case “chicken-sentience” is the slug.
Website Production Library
—Briefings
——chicken-sentience Briefing
———Fact Check
————2025-01-31-chicken-sentience-briefing-fact-check-initial.docx
————2025-08-12-chicken-sentience-briefing-fact-check-update.docx
————Verification Files
—————Avian Brains and a New Understanding of Vertebrate Brain Evolution.pdf
—————Rogers, Lesley J. The Development of Brain…214-215.pdf
The fact-check update documents may contain fact checks for multiple briefings, depending on the workflow. In that case, the fact-check document will be duplicated into multiple Fact Check briefing folders.
Within the Fact Check folder, there may be a subfolder named “Verification Files.” This folder contains supporting materials used for fact-checking, including PDFs, screenshots, and other documentation. These files provide evidence for claims in the briefing, especially when sources are behind paywalls or otherwise not publicly accessible. The fact checker will have access to these files.
Note: We started the fact-check documents in Google Docs before switching to MS Word, so the docx files for the first 33 briefings were converted from Google Docs. This explains the poor formatting and the lack of comment dates in these converted documents.
Featured and Social Images Folder
About Featured and Social Images
All briefings must include a Featured Image and a Social Image. Normally, pages do not have a Featured Image, but they may optionally have a Social Image depending on the likelihood and usefulness of the page being shared.
The featured image is a vertical 5:7 aspect-ratio PNG, uploaded with the tall side at 1920 pixels. It is almost always without text. A current exception to the text rule is a portrait of Tom Regan with his name at the bottom, whose image is unlikely to be known to many of our readers. Featured images are used in briefing listings like the home page and in the header of each briefing webpage.
The social image displays the featured image on the right, along with the title, URL, and decorative elements on the left. It is a 1920×1080-pixel JPG. It is used for social media sharing. Below is an example of a Featured Image and a Social Image.
Folder and Naming Conventions
The Featured and Social Image folder holds the featured image, the social image, and an Assets folder containing any files used in their creation. The following example illustrates the acceptable naming conventions:
Website Production Library
—Briefings
——environment Briefing
———Featured and Social Images
————environment-briefing-featured-image.jpg
————environment-briefing-social-image.png
————Assets
—————environment-briefing-featured-image.af
The featured image is typically assembled, edited, and adjusted in an Affinity Studio file (.af) in the Assets folder. Affinity Studio is a multi-platform software app that combines the most used features of Adobe Photoshop, Illustrator, and InDesign. This could also be a Photoshop file, as Affinity Studio can import and export them.
The social image for a briefing includes the featured image, the title, the briefing URL, and decorative elements. It is assembled in a PowerPoint file containing Social Images for all briefings, with one slide per briefing.
This PowerPoint file for briefings is shown below. The one for pages has not been created at the time of this writing but would be in the Pages folder instead of the Briefings folder.
Website Production Library
—Briefings
——aa Social Images for All Briefings
———social-images-for-all-briefings-v3.pptx
———zz Archive
————social-images-for-all-briefings-v2.pptx
We compile all Social Images into a single PowerPoint file to ensure consistency. A new Social Image is created by duplicating a slide or creating a new slide with the social image layout. The slide is then edited and exported as a PNG into the corresponding Featured and Social Images folder for the briefing.
Quick Look
You can get a quick look at all the Social Image files for briefings by going to the grid view at vbriefings.org/grid.
Flashcards Folder
This folder will be present if the briefing has flashcards. Flashcards are maintained in Brainscape. One Brainscape deck corresponds to one briefing. These decks are in the Brainscape class named vBriefings, which is publicly shared. There is another deck named staging, used to collaboratively edit decks, and it is not publicly shared.
After a deck is created or edited in Brainscape, it is exported as a CSV file and placed in the Flashcards folder. This is for backup in case Brainscape closes down, changes terms unacceptably, or our Brainscape data becomes corrupted. Like slides, these are versioned, and the version number should be incremented with each substantive change. Below are the flashcard files for the hunger briefing; the files for other briefings should follow the same pattern:
Website Production Library
—Briefings
——hunger Briefing
———Flashcards
————hunger-briefing-flashcards-v3.csv
————hunger-briefing-flashcards-v4.csv
Future Edits Folder
This folder contains information collected regarding potential future edits and additions to the briefing.
Research Folder
In this folder, you will find assets that were used in researching the briefing. There may or may not be a folder structure within this folder, depending on the needs of the briefing or page.
Slides Folder
If a briefing has a companion slide deck, you will find one or more PowerPoint (.pptx) files in this folder. The files will have version numbers, and the highest version is the production file linked in the briefing.
As an example, for the hunger briefing you will find this structure, and other briefings should follow the same pattern:
Website Production Library
—Briefings
——hunger Briefing
———Slides
————hunger-briefing-slides-v7.pptx
————hunger-briefing-slides-v8.pptx
The slides folder may have an Assets folder if needed.
Important: The share link for the latest version is entered into the WordPress briefing. There are two important things to remember here:
1. When you create the share link, be sure it is read-only and not editable. Unfortunately, OneDrive defaults to edit, so care must be taken.
2. When you create a new version, don’t create it in a new file, or create it by using “save as” because that would break the share link. Renaming the file doesn’t disable the share link, so follow this procedure for new versions:
- Duplicate the current version
- Rename the current version to increment the version number.
- Rename the copied file to remove “copy” from the file name.
- Continue editing with the new version, which is now the previous version with the version number incremented.
Videos Folder
Briefings and pages with at least one companion video will include a Videos folder. For each video, there will be a subfolder containing the video and its assets.
Example:
Website Production Library
—Briefings
——cruel Briefing
———Videos
———— cruel Briefing Video Why Do You Vegans
—————Assets
——————canva-link.txt
—————— why-do-you-vegans-partial1.mp4
—————— why-do-you-vegans-partial2.mp4
—————— why-do-you-vegans-partial3.mp4
—————— …
————— cruel-briefing-video-why-do-you-vegans-1609-36s.mp4
————— cruel-briefing-video-why-do-you-vegans-0916-36s.mp4
Online Video Editing
If the video is edited using an online tool, include a link to the source file in a text file named [tool]-link.txt in the assets folder. Examples:
canva-link.txt
Multiple Aspect Ratios
As shown above, videos with different aspect ratios should be stored in the same folder. The folder represents the video content, not a specific render format. All variants should share the same base filename and differ only by aspect ratio.
Examples (from above):
cruel-briefing-video-why-do-you-vegans-1609-36s.mp4
cruel-briefing-video-why-do-you-vegans-0916-36s.mp4
Folder Name
Each video should be stored in a subfolder using the following format:
slug Briefing Video [title or type]
The descriptive portion may be either the full title or a short descriptor (e.g., Announcement). Examples:
soy Briefing Video Announcement
hunger Briefing Video Why Do You Vegans
File Name
The video filename should:
- Begin with the folder name converted to lowercase
- Replace spaces with dashes
- Append the aspect ratio
- Append the duration
- End with .mp4
Examples:
brain-briefing-announcement-1609-1m16s.mp4
hunger-briefing-why-do-you-vegans-45-36s.mp4
The aspect ratio should:
- List the vertical dimension first
- Use digits only
- Use equal digit counts for both values
Valid examples:
0916
45
The duration should be written using the format:
0m0s
Replace the digits with the actual time. If the video is less than one minute, omit the minutes.
Examples:
1m16s
36s
Note: Do not alter formatting, separators, capitalization, or ordering, even if alternatives appear equivalent. Consistency is required for automation and long-term maintainability.
Visuals Folder
The visuals folder is similar to the videos folder in that each visual has its own directory.
Any software files (.pptx, .af, .psd), and any image files used to create them are in an Assets subfolder. The images are exported from a software file into parent folder. For example, a visual may be constructed in a PowerPoint file in the Assets folder, then exported as a PNG or JPG to its parent folder.
If the source for these visuals is in the PowerPower file for the briefing, place a note in a text file in the Assets folder. If all the visuals are from the Slides, you can for forgo having a directory for each visual.
Example
Assets
—slides-source.txt
——”The source files for these visuals are in the slides PowerPoint for this briefing.”
The naming conventions follow a pattern similar to that used for videos.
Website Production Library
—Briefings
——veganism Briefing
———Videos
———— veganism Briefing Visual Key Points
—————Assets
—————— veganism-briefing-visual-key-points-0916.pptx
—————— veganism-briefing-visual-key-points-1609.pptx
————— veganism-briefing-visual-key-points-0916.jpg
————— veganism-briefing-visual-key-points-1609.jpg