Documents are standalone webpages for your Flatfile Spaces. They can be rendered from Markdown syntax.

Often used for getting started guides, Documents become extremely powerful with dynamically generated content that stays updated as Events occur.

Flatfile also allows you to use HTML tags in your Markdown-formatted text. This is helpful if you prefer certain HTML tags rather than Markdown syntax. Links in documents (both Markdown and HTML) automatically open in a new tab to ensure users don’t navigate away from the Flatfile interface.

An example Welcome Document with steps for data import

​
Key Features

A note on Documents: While Documents themselves can be created and updated dynamically, the content inside of a document should be considered to be static - that is, you cannot use documents to host interactive elements or single-page webforms. For that sort of functionality, we recommend using Actions to trigger a Listener to perform the desired functionality.

​
Markdown-Based Content

Documents support GitHub-flavored Markdown, allowing you to create rich, formatted content with headers, lists, code blocks, and more. You can also use HTML tags within your Markdown for additional formatting flexibility.

​
Dynamic Content

Documents can be created and updated programmatically in response to Events, enabling dynamic content that reflects the current state of your Space or data processing workflow.

​
Document Actions

Add interactive buttons to your Documents that trigger custom operations. Actions appear in the top right corner and can be configured with different modes, confirmations, and tooltips.

​
Embedded Blocks

Documents support embedding interactive data blocks (Workbooks, Sheets, and Diffs) directly within the content. See the Adding Blocks to Documents section for detailed implementation.

​
Ephemeral Documents

Documents with the “ephemeral” treatment appear as full-screen takeovers and don’t show in the Space sidebar, creating focused user experiences.

​
Create a Document

You can create Documents upon Space creation using the Space Configure Plugin, or dynamically in a Listener using the API:

import api from "@flatfile/api";

export default function flatfileEventListener(listener) {
  listener.on("file:created", async ({ context: { spaceId, fileId } }) => {
    const fileName = (await api.files.get(fileId)).data.name;
    const bodyText =
      "# Welcome\n" +
      "### Say hello to your first customer Space in the new Flatfile!\n" +
      "Let's begin by first getting acquainted with what you're seeing in your Space initially.\n" +
      "---\n" +
      "Your uploaded file, ${fileName}, is located in the Files area.";

    const doc = await api.documents.create(spaceId, {
      title: "Getting Started",
      body: bodyText,
    });
  });
}

This Document will now appear in the sidebar of your Space. Learn how to customize the guest sidebar for different user types.

In this example, we create a Document when a file is uploaded, but you can also create Documents in response to any other Event. Read more about the different Events you can respond to.

​
Document Actions

Actions are optional and allow you to run custom operations in response to a user-triggered event from within a Document.

Define Actions on a Document using the actions parameter when a document is created:

import api from "@flatfile/api";

export default function flatfileEventListener(listener) {
  listener.on("file:created", async ({ context: { spaceId, fileId } }) => {
    const fileName = (await api.files.get(fileId)).data.name;
    const bodyText =
      "# Welcome\n" +
      "### Say hello to your first customer Space in the new Flatfile!\n" +
      "Let's begin by first getting acquainted with what you're seeing in your Space initially.\n" +
      "---\n" +
      "Your uploaded file, ${fileName}, is located in the Files area.";

    const doc = await api.documents.create(spaceId, {
      title: "Getting Started",
      body: bodyText,
      actions: [
        {
          label: "Submit",
          operation: "contacts:submit",
          description: "Would you like to submit the contact data?",
          tooltip: "Submit the contact data",
          mode: "foreground",
          primary: true,
          confirm: true,
        },
      ],
    });
  });
}

Then configure your listener to handle this Action, and define what should happen in response. Read more about Actions and how to handle them in our Using Actions guide.

Actions appear as buttons in the top right corner of your Document.

​
Document treatments

Documents have an optional treatments parameter which takes an array of treatments for your Document. Treatments can be used to categorize your Document. Certain treatments will cause your Document to look or behave differently.

​
Ephemeral documents

Giving your Document a treatment of "ephemeral" will cause the Document to appear as a full-screen takeover, and it will not appear in the sidebar of your Space like other Documents. You can use ephemeral Documents to create a more focused experience for your end users.

const ephemeralDoc = await api.documents.create(spaceId, {
  title: "Getting started",
  body: "# Welcome ...",
  treatments: ["ephemeral"],
});

Currently, "ephemeral" is the only treatment that will change the behavior of your Document. Other treatments will not affect how your Document behaves, but can be used for your own purposes to categorize and describe your Documents in code.

​
Adding Blocks to Documents

Blocks are dynamic, embedded entities that you can use to display data inside a Document. You can add a Block to a Document using the <embed> HTML entity in your markdown and specifying which Block type you want to show using the type attribute on the entity. Three Block types are currently supported: Embedded Workbook, Embedded Sheet, and Embedded Diff.

​
Embedded Workbook

Use this Block to render an entire Workbook with all its Sheets inside a Document, providing users with tabbed navigation between sheets. You can embed a Workbook by passing a workbook ID and optional name. You can also control whether the embedded Workbook is expanded when the document loads and whether to show the header.

const doc = await api.documents.create(spaceId, {
  title: "Getting started",
  body:
    "# Welcome\n" +
    "\n" +
    "Here is an embedded Workbook:\n" +
    "\n" +
    "<embed type='embedded-workbook' name='Customer Data' defaultExpanded='true' showHeader='true' workbookId='your_workbook_id'>\n" +
    "\n" +
    "Here is another embedded Workbook without header:\n" +
    "\n" +
    "<embed type='embedded-workbook' showHeader='false' workbookId='us_wb_8e0z52gI'>",
});

Properties:

  • workbookId (required): The ID of the workbook to embed
  • name (optional): Display name for the embedded workbook
  • defaultExpanded (optional): Whether the workbook is expanded when the document loads (defaults to false)
  • showHeader (optional): Whether to show the workbook header (defaults to true). When false, the workbook is automatically expanded

​
Embedded Sheet

Use this Block to render a Sheet along with all its data inside of a Document. You can embed a Sheet into your Document by passing a sheet ID, workbook ID, and name. You can also specify whether the embedded Sheet is expanded or collapsed when the document is loaded, and whether to show the header.

You can include as many embedded Sheets in your Document as you like, but end users will only be able to expand a maximum of 10 embedded Sheets at once.

const doc = await api.documents.create(spaceId, {
  title: "Getting started",
  body:
    "# Welcome\n" +
    "\n" +
    "Here is an embedded Sheet:\n" +
    "\n" +
    "<embed type='embedded-sheet' name='Contacts' defaultExpanded='true' showHeader='true' sheetId='your_sheet_id' workbookId='your_workbook_id'>\n" +
    "\n" +
    "Here is another embedded Sheet without header:\n" +
    "\n" +
    "<embed type='embedded-sheet' name='Countries' showHeader='false' sheetId='us_sh_TVW95224' workbookId='us_wb_8e0z52gI'>",
});

Properties:

  • sheetId (required): The ID of the sheet to embed
  • workbookId (required): The ID of the workbook containing the sheet
  • name (optional): Display name for the embedded sheet
  • defaultExpanded (optional): Whether the sheet is expanded when the document loads (defaults to false)
  • showHeader (optional): Whether to show the sheet header (defaults to true). When false, the sheet is automatically expanded

​
Embedded Diff

Use this Block to show a side-by-side comparison of the data in a Sheet now versus at a previous point in time as captured by a Snapshot. Pass a Sheet ID, Workbook ID, and Snapshot ID. You can optionally pass a direction attribute which specified whether the changes are displayed with the Snapshot as the end state (sheet_to_snapshot) or the Sheet as the end state (snapshot_to_sheet). The default value for direction is sheet_to_snapshot.

Use direction="sheet_to_snapshot" if you want to show changes that have been made since the time the Snapshot was taken, i.e. to review past changes. Use direction="snapshot_to_sheet" if to preview the changes that would occur if you were to revert your Sheet back to the state it was in when the Snapshot was taken.

const doc = await api.documents.create(spaceId, {
  title: 'Getting started',
  body:
    "# Welcome\n" +
    "\n" +
    "Here is an embedded Diff:\n" +
    "\n" +
    "<embed type='embedded-diff' sheetId='your_sheet_id' workbookId='your_workbook_id' snapshot_id='your_snapshot_id" direction="snapshot_to_sheet">"
  ,
})

​
Markdown reference

Documents support Github-flavored Markdown. Check out this guide for a full reference on the entities you can use.

​
Example Project

Find the documents example in the Flatfile GitHub repository.

  • TypeScript - Clone the documents example in TypeScript
  • JavaScript - Clone the documents example in JavaScript

Documents work closely with other Flatfile concepts:

  • Listeners create and update Documents in response to Events
  • Spaces contain Documents alongside other resources
  • Actions can be triggered from Document buttons
  • Jobs may update Documents to show progress
  • Workbooks and their Sheets can be embedded within Documents
  • Records can be displayed through embedded Sheets in Documents