Writing content in markdown

Each piece of content on ActivistChecklist.org is an .mdx file. Every file has two parts:

A frontmatter block at the top (between the --- lines) with structured metadata.
The actual content, formatted with markdown. Can contain markdown components. (If you’re new to markdown, check out this markdown cheat sheet for reference.)

If you’re using the visual editor, most of this is handled for you. But if you’re editing files directly, this page is your reference.

See page structure & formatting for guidance on what to write. This page covers how to format it in markdown.

Pages

Pages are standalone informational content such as the About page, the Privacy page, and Resources. No checklist structure, just text. Files live in /content/en/pages/.

---
title: About This Site
firstPublished: 2025-01-09
lastUpdated: 2026-01-23
---

We started Activist Checklist because we were seeing a lot of confusion and
inaction around digital security in Palestine solidarity organizing...

## Why we built this site

Looking around, we found that existing resources were either too simple or
too complicated. We wanted to create a comprehensive approach that
wouldn't make your eyes glaze over.

<Alert type="info">
  We are currently choosing to remain anonymous to preserve our own privacy
  given the risks involved in this work.
</Alert>

## Our sources

We draw on a number of sources...

Frontmatter fields:

Field	Required?	What it’s for
`title`	Required	The page title
`firstPublished`	Optional	When it was first published (`YYYY-MM-DD`)
`lastUpdated`	Optional	When it was last updated (`YYYY-MM-DD`)

Guides

Guides are the main checklist pages, such as “Security Essentials” or “Prepare for a Protest.” They use a structured format with sections and checklist items. Files live in /content/en/guides/.

---
title: Prepare for a Protest
estimatedTime: 30 minutes
excerpt: >
  When police access one person's phone, they can map entire activist
  networks. The steps here are designed to help protect not just you,
  but the networks connected to you.
relatedGuides:
  - essentials
  - signal
firstPublished: 2024-12-11
lastUpdated: 2026-03-18
---

When police access one person's phone, they can map entire activist networks
(your contacts, your Signal chats, your location history, and more). The steps
here are designed to help protect not just you, but the networks connected
to you.

**Who this checklist is for:** Anyone attending protests, direct actions,
or demonstrations where police presence is expected.

<Section title="Baseline phone protections" slug="phone-baseline">
  <RiskLevel level="everyone" mode="single_line">
    This section is for anyone attending a low-risk protest. Organizers
    and higher-risk participants should also do the sections below.
  </RiskLevel>

  <ChecklistItemGroup>
    <ChecklistItem slug="biometrics-disable" />
    <ChecklistItem slug="passcode" />
    <ChecklistItem slug="signal-at-protests" />
    <ChecklistItem slug="location" />
  </ChecklistItemGroup>
</Section>

<Section title="Enhanced protections" slug="enhanced">
  <RiskLevel level="medium" mode="for_you_if">
    * **You're an organizer or visible leader** in social movement spaces.
    * **You're likely to be targeted** based on identities you hold.
    * **You have close connections** to many at-risk individuals.
  </RiskLevel>

  <ChecklistItemGroup>
    <ChecklistItem slug="vpn" />
    <ChecklistItem slug="lockdown" />
    <ChecklistItem slug="secure-phone" />
  </ChecklistItemGroup>
</Section>

Frontmatter fields:

Field	Required?	What it’s for
`title`	Required	Guide title (action-oriented or descriptive)
`estimatedTime`	Optional	e.g. `30 minutes`
`excerpt`	Optional	1- to 2-sentence description shown on the homepage and listings
`relatedGuides`	Optional	List of guide slugs linked at the bottom (“Keep learning”). Can have 0 to 4.
`firstPublished`	Optional	`YYYY-MM-DD`
`lastUpdated`	Optional	`YYYY-MM-DD`

See the components reference below for details on <Section>, <RiskLevel>, <ChecklistItem>, and <ChecklistItemGroup>.

Checklist items

Checklist items are the individual action steps. Each one lives in its own file inside /content/en/checklist-items/.

---
title: Set your phone passcode to 8 to 10 random digits
preview: >
  It takes years for cops to crack an 8-digit random passcode. They can
  probably guess your current passcode in less than 5 minutes with
  automated tools.
do: >
  Use a random passcode generator to create an 8 to 10-digit code
dont: >
  Use any passcode you thought of yourself (dates, patterns on the
  keyboard, etc.). Do not use 6-digit passcodes if possible.
titleBadges: []          # or: [important]
firstPublished: 2025-05-12
lastUpdated: 2026-01-31
---

Context paragraph: name the threat in plain language, then explain how
this step helps. Keep it to 1–3 paragraphs.

<HowTo title="How to change your passcode">
  1. Generate a random 8 to 10-digit passcode using this
     [random passcode generator](https://strongphrase.net/passcode).
     (Don't make one up yourself, humans are bad at random!)
  2. Change your passcode:

     <MenuPath>*iPhone:* **Settings** > **Face ID & Passcode** > **Change Passcode** > **Passcode Options** > **Custom Numeric Code**</MenuPath>

     <MenuPath>*Android:* **Settings** > **Security** > **Screen Lock** > **PIN/Password**</MenuPath>

  3. **Practice it** at least 10 times right now so you're more likely
     to remember it.
</HowTo>

Notes, caveats, and alternatives go after the HowTo block.

<Alert type="warning">
  A 6-digit passcode is much weaker — even a random one. Use 8 to 10
  digits if at all possible.
</Alert>

Frontmatter fields:

Field	Required?	What it’s for
`title`	Required	Imperative statement of what to do, e.g. “Set your phone passcode to 8 to 10 random digits.” Try to make this clear enough that someone could do it without expanding the item if they were motivated and tech-savvy enough.
`preview`	Recommended	1 to 2 sentence benefit (or risk) to mention. Shows while checklist item is collapsed.
`do`	Optional	👍 The DO recommendation
`dont`	Optional	👎 The DON’T recommendation
`titleBadges`	Optional	Array. Adds a badge next to the title. Only one value is available: `[important]`. Leave as `[]` to show no badge.
`firstPublished`	Optional	`YYYY-MM-DD`
`lastUpdated`	Optional	`YYYY-MM-DD`

do and dont usually go together. Try to include both or neither.

Images & files

Images

Images live in /public/images/content/ in the repo. To add a new image, add the file there and reference it with a standard Markdown image tag:

![Alt text describing the image](/images/content/your-image.png)

Use descriptive alt text. It helps screen readers and shows when the image fails to load.

Downloadable files

PDFs and other downloads live in /public/files/downloads/. Link to them like any other link:

[Download the planning worksheet (PDF)](/files/downloads/your-file.pdf)

Uploading via the visual editor

If you’re using the visual editor, you can upload images directly through the editor interface. No need to add them to the repo manually.

Components reference

`<Section>`

Wraps a section. Can be a section containing just text, or a section containing checklist items. Can be used on a Page or a Guide.

Prop	Required?	What it’s for
`title`	Required	Section heading shown to readers
`slug`	Optional	URL anchor for the section

`<RiskLevel>`

Shows the risk-level indicator at the top of a section. Goes inside <Section>, before <ChecklistItemGroup>.

Use anytime the sections on a checklist are grouped by risk level.

Prop	Required?	What it’s for
`level`	Required	`everyone`, `medium`, or `high`
`mode`	Required	`default`: use the pre-defined risk message for that level `single_line`: write a custom message for this section that says “This section is for” `for_you_if`: bulleted “This section is for you if…” list

`<ChecklistItemGroup>` and `<ChecklistItem>`

<ChecklistItemGroup> wraps a set of checklist items. Always use it to wrap multiple checklist items, don’t place <ChecklistItem /> components outside of one.

<ChecklistItem slug="..." /> loads a checklist item by its slug. The slug is the filename without .mdx and must exist in /content/en/checklist-items/.

<ChecklistItemGroup>
  <ChecklistItem slug="passcode" />
  <ChecklistItem slug="biometrics-disable" />
</ChecklistItemGroup>

`<Alert>`

Use <Alert> anywhere in guide body or checklist item content to flag something worth calling out.

We almost never use the title property. Instead, we put a few bold words at the start of the alert to make it stand out.

Can contain markdown.

<Alert type="info">
  An aside or FYI. Good for context that doesn't fit in the main flow.
</Alert>

<Alert type="info" title="Easier with a crew">
  Most people mean to get around to these steps and never do. Consider
  working through this list with friends at a [security party](/party/).
</Alert>

<Alert type="success">
  **iPhone tip:** Press the side button 5 times to force your passcode
  to be used for the next unlock — even if Face ID is enabled.
</Alert>

<Alert type="warning">
  **A VPN doesn't make you fully anonymous.** For sensitive browsing,
  consider [Tor Browser](https://www.torproject.org/) alongside your
  everyday browser.
</Alert>

Prop	Required?	Notes
`type`	Optional	`info`: an aside, FYI, or context that doesn’t fit the main flow `success`: an encouraging tip, shortcut, or good-news moment `warning`: a caution, limitation, or gotcha the reader shouldn’t miss Defaults to `info` if omitted
`title`	Optional	Adds a bold heading at the top of the callout

`<HowTo>`

The <HowTo> tag contains the actual steps someone needs to take. Everything before/after it is context about why this is important and additional notes.

It is almost always used inside a checklist item.

Can contain markdown.

<HowTo title="How to set up Signal">
  1. [Install Signal](https://signal.org/) on your phone.
  2. Enable disappearing messages:

     <MenuPath>*iPhone:* Open Signal > Tap your profile picture > **Settings** > **Privacy** > **Disappearing Messages** > **Set your default timer**</MenuPath>

     <MenuPath>*Android:* Open Signal > Tap your profile picture to open **Settings** > **Privacy** > **Default Timer After Reading** > **Set your default timer**</MenuPath>

  3. [Follow the Signal Security Checklist](/signal/) for more steps.
</HowTo>

Prop	Required?	What it’s for
`title`	Required	Heading shown at the top of the box. Always starts with “How to…”

For UI navigation paths inside (or outside) a <HowTo>, use the <MenuPath> component. It handles platform headers, separator arrows, and accessibility for you.

`<MenuPath>`

Formats UI navigation paths consistently across the site. Use it anywhere you have a “Settings > Privacy > Screen Lock”-style sequence, in a <HowTo> or in body prose.

The component renders separators as styled arrows, attaches a platform icon when it recognises the header (iPhone, Android, Mac, macOS, Windows), and announces the separator to screen readers as the localized word “then.”

Block form (default)

Stands as its own block with an optional platform header on the line above the path. Use this when the path is the main content of the step.

<HowTo title="How to disable Signal notifications">
  <MenuPath>*iPhone:* Open Signal > Tap your profile picture > **Settings** > **Notifications** > **Notification Content** > Select **No Name or Content**</MenuPath>
  <MenuPath>*Android:* Open Signal > Tap your profile picture to open **Settings** > **Notifications** > **Show** > Select **No name or message**</MenuPath>
</HowTo>

Inline form

Sits inside a sentence in surrounding prose. No header is rendered.

Enable disappearing messages by default: <MenuPath inline>Open Signal > Tap your profile picture > **Settings** > **Privacy** > **Disappearing Messages** > set to your desired time</MenuPath>.

Prop	Required?	What it’s for
`inline`	Optional	Boolean. Renders inline (no header, no block spacing). Defaults to block.

Authoring rules

Platform header (block form only). If the path is platform-specific, start with an italic-and-colon header like *iPhone:*, *Android:*, *Mac:*, *macOS:*, or *Windows:*. The component strips the colon and italics for display and adds a brand icon (Apple for iPhone and Mac, Android, Windows). It also auto-strips a leading “On ”, so write *iPhone:* rather than *On iPhone:*. Italic-colon headers for unknown platforms (*Brave:*, *Firefox:*) work too; they just render without an icon.

Separator. Write > between steps. The component renders it as → (or ← in right-to-left languages). You can write → directly if you prefer; the component recognises both.

Bold what is on screen. Bold every literal label the reader will see and tap. Don’t bold:

Action verbs: Open, Tap, Click, Select, Press, Toggle off, Enable, Disable
App names used as containers, like “Open Signal” or “Open Brave”
Descriptive phrases like “your profile picture,” “the search icon,” “the @ symbol”
Bracketed placeholders like \[App Name]
The italic platform header itself

Open Signal > Tap your profile picture > **Settings** > **Notifications** > **Show** > Select **No name or content**

Strip wrapping quotes around UI labels. Quotes around button or option names get dropped.

Don’t	Do
`"Disable iPhone Unlock"`	`Disable iPhone Unlock`
`Select "Never"`	`Select Never`

Side notes go outside. If a parenthetical or aside isn’t part of the path, pull it out after the closing tag.

<MenuPath>*iPhone:* **Settings** > **Privacy & Security** > Disable **Location Services**</MenuPath>

*(Quicker shortcut: Say to Siri "Disable location tracking")*

A trailing sentence-style step belongs inside the path, even when it’s not a tappable label.

<MenuPath inline>Open Signal > Tap your profile picture > **Settings** > **Privacy** > **Disappearing Messages** > set to your desired time</MenuPath>.

Signal paths

Signal paths follow a fixed shape across the site:

Context	Format
Non-platform Signal path	`Open Signal > Tap your profile picture > Settings > ...`
iPhone-only Signal path	`iPhone: Open Signal > Tap your profile picture > Settings > ...`
Android-only Signal path	`Android: Open Signal > Tap your profile picture to open Settings > ...`

On Android, tapping the profile picture opens Settings directly, so the platform-distinguished form collapses those two steps into “Tap your profile picture to open Settings” (one segment, no chevron between).

Right-to-left support

The component picks the locale-correct arrow (→ for LTR, ← for RTL) automatically based on the active locale. Authors don’t need to do anything different for RTL languages.

`<InlineChecklist>`

Converts a bullet list inside a <HowTo> into an interactive checklist readers can tick off. Use it when you have a list of steps that don’t have a strict order, such as a settings checklist where each item is independent.

<HowTo title="How to configure Signal">
  <InlineChecklist>
    * **Enable disappearing messages by default:**

      <MenuPath inline>Open Signal > Tap your profile picture > **Settings** > **Privacy** > **Disappearing Messages** > set a time</MenuPath>

    * **Create a username** and share that instead of your phone number:

      <MenuPath inline>Open Signal > Tap your profile picture > **Settings** > Tap your name > Tap the **@** symbol > **Set username**</MenuPath>

    * **Hide message previews in notifications:**

      <MenuPath inline>Open Signal > Tap your profile picture > **Settings** > **Notifications** > **Notification Content** > Select **No Name or Content**</MenuPath>
  </InlineChecklist>
</HowTo>

No props. Just wrap a bullet list with it inside a <HowTo>.

Writing content in markdown

Pages

Guides

Checklist items

Images & files

Images

Downloadable files

Uploading via the visual editor

Components reference

<Section>

<RiskLevel>

<ChecklistItemGroup> and <ChecklistItem>

<Alert>

<HowTo>

<MenuPath>

Block form (default)

Inline form

Authoring rules

Signal paths

Right-to-left support

<InlineChecklist>

`<Section>`

`<RiskLevel>`

`<ChecklistItemGroup>` and `<ChecklistItem>`

`<Alert>`

`<HowTo>`

`<MenuPath>`

`<InlineChecklist>`