> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockli.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Editing Content with blökkli: A Step-by-Step Workflow

> Learn how content editors add, move, configure, and publish blocks in blökkli. Covers drag-and-drop, options, history, and publishing.

This guide walks through a typical content editing session with blökkli — from opening the editor to publishing your changes. Each step maps to a distinct part of the editor interface, so you can follow along on any page that uses the blökkli provider.

<Tip>
  **Multi-select:** Hold **Shift** and click multiple blocks to select them as a group. You can then move, delete, or apply options to all selected blocks at once — a significant time-saver when reorganising a long page.
</Tip>

<Steps>
  <Step title="Open the editor">
    Navigate to the page you want to edit and append the editing query parameter to the URL:

    ```text theme={null}
    https://your-site.com/your-page?blokkliEditing={entity-uuid}
    ```

    Replace `{entity-uuid}` with the UUID of the entity you want to edit. The editor overlay activates immediately — no page reload required. The toolbar appears at the top and block handles become available as you hover over content.

    <Note>
      `can-edit` must be `true` on your `<BlokkliProvider>` for the editor to activate. If the overlay doesn't appear, check that the current user has edit permissions for this entity.
    </Note>
  </Step>

  <Step title="Add a new block">
    To insert a new block onto the page, you have two options:

    **Using the toolbar button:**

    1. Click the **+** button in the toolbar to open the Add Block panel.
    2. Browse or search the list of available bundle types.
    3. Click a bundle to append a new block of that type to the bottom of the current field.

    **Using drag-and-drop:**

    1. Open the Add Block panel with the **+** button.
    2. Drag a bundle type from the panel directly onto the page.
    3. Drop it at the exact position you want — a drop indicator shows where the block will be inserted.

    The new block appears at your chosen position and is automatically selected, ready for configuration.
  </Step>

  <Step title="Reorder blocks">
    Every block has a drag handle that appears when you hover over it. To reorder blocks:

    1. Hover over the block you want to move — the drag handle appears on the block's edge.
    2. Click and hold the drag handle.
    3. Drag the block to its new position. A drop indicator shows valid insertion points.
    4. Release to drop the block at that position.

    You can drag blocks within the same field or move them to a different field on the same page. blökkli calls the appropriate adapter method (`moveBlock` or `moveMultipleBlocks`) to persist the change.
  </Step>

  <Step title="Configure a block">
    Block options let you change the appearance and behaviour of a block without editing its content — things like layout variant, colour scheme, spacing, or visibility.

    1. Click any block to select it.
    2. The **Options panel** slides in from the right.
    3. Adjust any option value — the block updates live in the preview as you make changes.
    4. Click elsewhere or press **Esc** to deselect the block and close the options panel.

    Option changes are staged as mutations and included in the next publish action.
  </Step>

  <Step title="Edit block content">
    To change the actual content of a block (text, images, references, and other fields managed by your backend):

    1. Click a block to select it.
    2. Click the **edit (pencil) icon** on the block handle or in the selection toolbar.
    3. An edit form opens in an overlay iframe. This form is rendered by `formFrameBuilder()` in your adapter — it can be any URL your backend provides.
    4. Fill in the form fields and submit.
    5. The block's props update and the live preview reflects the new content.

    The form lifecycle (open, submit, close) is fully controlled by your adapter's `formFrameBuilder()` implementation, giving you complete flexibility over the editing UI.
  </Step>

  <Step title="Undo and redo">
    Every mutation in blökkli is tracked and reversible.

    * Press **Ctrl + Z** (Windows/Linux) or **⌘ Z** (Mac) to undo the last action.
    * Press **Ctrl + Shift + Z** (Windows/Linux) or **⌘ Shift + Z** (Mac) to redo.

    For a complete view of your change history, click the **clock icon** in the toolbar to open the History panel. It shows every mutation in the current session as a labelled timeline entry. Click any entry to jump the editing state back to that point — all subsequent mutations are preserved as a branch you can redo forward again.
  </Step>

  <Step title="Preview changes">
    Before publishing, check how the page looks without the editor overlay.

    * Click the **Preview** button in the toolbar (or use the `preview` feature shortcut) to toggle the editor overlay off. Your staged changes remain in place — you're simply viewing the page as a visitor would see it.
    * Use **Responsive Preview** to check the layout at different screen sizes. Switch between mobile, tablet, and desktop viewports without leaving the editor.

    Click the preview button again to return to editing mode.
  </Step>

  <Step title="Publish">
    When you're happy with your changes, publish them to make them visible to all visitors.

    1. Click **Publish** in the toolbar.
    2. blökkli calls the `publish()` method in your adapter, passing all staged mutations.
    3. Your adapter persists the changes to your backend.
    4. The editor closes and the page displays the freshly published content.

    If you want to discard all unpublished changes instead, use the **Revert** feature (available from the toolbar overflow menu) to reset the page back to its last published state.
  </Step>
</Steps>