How to Build a Mastodon Read-Only Mirror From Export Archive

You have left a Mastodon instance or deactivated your account, but you want your old posts to remain publicly accessible. A read-only mirror built from your Mastodon export archive lets you preserve every toot without needing a live account. This article explains how to generate the archive inside Mastodon and then publish it as a static website. You will need a web hosting space that supports HTML files or a service like GitHub Pages.

A Mastodon export archive contains all your posts, media, and account metadata in a machine-readable format. By converting this archive into a static site, you create a permanent, searchable record of your content. The process takes about 30 minutes and requires no coding beyond editing a few configuration lines. The result is a mirror that displays your toots in chronological order, just like your original profile.

This guide covers two methods: using the official Mastodon archive tool and building a mirror manually with a static site generator. Both approaches produce a read-only site that respects your original post formatting and attached media.

What a Mastodon Export Archive Contains and Why You Need It

When you request your data export from Mastodon, the platform compiles a ZIP file named archive-export-YYYY-MM-DD.zip. Inside you will find three main components. The outbox.json file stores every toot you ever published, including replies, boosts, and direct messages. The media_attachments folder holds all images, videos, and files you uploaded. The actor.json file contains your profile information such as display name, bio, and avatar.

This archive is designed for data portability. You can import it into a new Mastodon account or, as this article describes, turn it into a standalone website. The archive does not include follower lists, follow requests, or server-side data like interaction counts. It is a complete record of your authored content only.

To build a mirror, you need a tool that understands the ActivityPub JSON format used in the archive. The outbox.json file follows the W3C Activity Streams 2.0 specification. Each post is an Announce or Create activity with nested objects containing the text, timestamps, and media references. A static site generator reads this structure and produces clean HTML pages.

Steps to Generate a Read-Only Mirror From Your Mastodon Export Archive

Method 1: Using Mastodon Archive Viewer (Recommended)

1. Request your archive from Mastodon
   Log into your Mastodon account. Go to Preferences > Import and export > Export. Click the button labeled Request your archive. Mastodon will email you a download link when the archive is ready, usually within a few minutes. Download the ZIP file and extract it to a folder on your computer.
2. Install Mastodon Archive Viewer
   Open a terminal or command prompt. Run the command pip install mastodon-archive-viewer. This installs the Python package that converts your archive into HTML. If you do not have Python installed, download it from python.org and install version 3.8 or later.
3. Run the conversion tool
   In the terminal, navigate to the folder where you extracted your archive. Run the command mastodon-archive-viewer --input outbox.json --output mirror. The tool creates a new folder named mirror containing an index.html file and subfolders for each post and media file. This process takes 10 to 30 seconds depending on the number of posts.
4. Preview the mirror locally
   Open the mirror folder and double-click index.html. Your browser displays a timeline of all your posts in reverse chronological order. Click any post to see its full text, timestamp, and attached media. Verify that images and videos load correctly.
5. Upload the mirror to a web host
   Upload the entire mirror folder to your web hosting service. If you use GitHub Pages, create a new repository, push the folder contents, and enable Pages in the repository settings. Your mirror will be live at yourusername.github.io/repositoryname.

Method 2: Manual Mirror With a Static Site Generator

1. Prepare your archive
   Same as Method 1, request and download your archive from Mastodon. Extract the ZIP file to a folder named archive.
2. Install Hugo or Jekyll
   Choose a static site generator. Hugo is faster for large archives. Download Hugo from gohugo.io and install it. Alternatively, install Jekyll by running gem install jekyll bundler.
3. Create a new site project
   Run hugo new site mirror-site or jekyll new mirror-site. This creates a folder with the basic structure for your site.
4. Write a conversion script
   The archive format is JSON, not Markdown. You need a small script to parse outbox.json and generate Markdown files for each post. Use a language like Python or Node.js. The script should extract the object.content field, convert HTML to Markdown if needed, and save each post as content/posts/post-id.md with front matter for date and title.
5. Build and deploy
   Run hugo or jekyll build to generate the static HTML in a public folder. Upload the public folder to your web host. This method gives you full control over the design but requires more technical effort.

Common Issues When Building a Mastodon Read-Only Mirror

Media Attachments Do Not Display After Upload

The archive includes media files in the media_attachments folder. When you run Mastodon Archive Viewer, it copies these files into the output folder. If images do not appear, check that the file paths in the generated HTML match the folder structure. Open the mirror folder and verify that the media subfolder exists and contains the expected files. If you uploaded only the HTML files, re-upload the entire mirror folder including the media directory.

Posts Appear Out of Order or Missing

The conversion tool sorts posts by the published timestamp in outbox.json. If your archive contains posts from multiple accounts or has corrupted JSON, the order may be wrong. Open outbox.json in a text editor and confirm that the JSON structure is valid. Use an online JSON validator to check for syntax errors. If you see missing posts, the archive may have been truncated by the Mastodon server due to size limits. Request a new archive and try again.

Direct Messages Appear in the Mirror

Mastodon includes direct messages in the export archive. Mastodon Archive Viewer filters them out by default, but the manual script method may include them. To remove direct messages, edit your conversion script to skip posts where object.to contains a private audience URI. The Mastodon Archive Viewer handles this automatically, so use Method 1 if you want to avoid exposing private content.

Item	Mastodon Archive Viewer	Manual Static Site Generator
Setup time	10 minutes	45 minutes
Technical skill required	Basic command line	Scripting and static site config
Media handling	Automatic	Manual path mapping
Direct message filtering	Built-in	Must be coded
Custom design options	Limited to default theme	Full control via templates

Your read-only mirror is now live and accessible to anyone with the URL. You can share the link on your new Mastodon profile or embed it on a personal website. To keep the mirror updated with future posts, generate a new archive each month and rebuild the site. For advanced users, add a sitemap.xml file to help search engines index your content. This ensures your old posts remain discoverable long after you leave the original instance.