DOCSEARCHbyAlgolia
Submit Docs

AlchemyCMS Documentation

website·Indexed 33 days ago

https://guides.alchemy-cms.com/

Guides and documentation for AlchemyCMS, a Rails Engine for content management. Includes instructions on getting started, configuring elements and ingredients, managing pages and menus, media library usage, internationalization, and deployment options including Kamal.

Tokens
47K
Snippets
312
Records
389
Agent score
62%

What's inside AlchemyCMS

  1. Overview of AlchemyCMS Architecture

    AlchemyCMS is a Rails engine that integrates into existing Ruby on Rails applications using standard conventions (ERB, ActiveRecord, asset pipeline). Unlike traditional CMSs, it stores only structured content (text, image references, richtext) rather than complete HTML pages, giving developers full control over markup and styling.

  2. Overview of AlchemyCMS Core Modules

    AlchemyCMS is a Ruby on Rails engine that provides six core modules for content management: Pages, Languages, Sites, Users, Tags, and Library (which handles Pictures & Attachments). These core modules can be extended by creating custom modules, which must be implemented as Rails engines that register themselves with Alchemy.

  3. Manage images with the Alchemy Picture Library

    The Picture Library is used to manage images that are assigned to Picture ingredients on elements. Alchemy stores the original image and generates resized variants dynamically. Key features include bulk uploading, tagging for organization, language-specific captions/descriptions, filtering (by format, tag, or date), and a built-in cropping tool. Note: Pictures currently assigned to elements cannot be deleted until they are removed from those elements.

  4. Create a post preview partial for the blog overview

    Create a _post_preview.html.erb partial to render a summary of each blog post on the overview page. This partial should extract the post_header element from the child page to display the teaser and hero image.
    <% cache(post) do %>
  <% header = post.elements.find_by(name: "post_header") %>
  <% return unless header %>
  <article class="post-preview">
    <% if header.ingredient_by_role(:image)&.picture %>
      <%= render header.ingredient_by_role(:image), size: "600x300", crop: true %>
    <% end %>
    <h2><%= link_to post.title, show_alchemy_page_path(post) %></h2>
    <time><%= l(post.public_on, format: :long) %></time>
    <p><%= header.ingredient_by_role(:teaser)&.value&.truncate(200) %></p>
  </article>
<% end %>

  5. Understand the AlchemyCMS content storing architecture

    AlchemyCMS separates content from presentation. Unlike CMSs that store full HTML markup, Alchemy only stores unformatted text, object IDs (such as attachments and pictures), and limited rich text in the database. It does not store HTML markup, CSS, styling, or layouts, giving the developer full control over the final markup and styling.

  6. Manage multi-language support in Alchemy

    Alchemy provides built-in multi-language support where each site can maintain multiple languages. Each language is independent, possessing its own page tree, menus, and content. Every language is defined by a language code (ISO 639-1) and an optional country code (ISO 3166). One language per site must be designated as the default, which serves as the fallback and is always public.

  7. Organize media and elements using Tags

    Tags in Alchemy CMS are used to organize pictures and attachments within the library, on pages, and within taggable elements. Editors can assign tags during the upload or editing process of media and use these tags to filter the library. The system is powered by the Gutentag tagging engine.

  8. Define blog elements in Alchemy CMS

    Blog elements are defined in config/alchemy/elements.yml. For a standard blog, you typically need a post header for metadata, repeatable text and image sections for content, and an overview element for the blog index page.
    # config/alchemy/elements.yml

# Post Header: Captures headline, author, hero image, and teaser
- name: post_header
  unique: true
  taggable: true
  ingredients:
    - role: headline
      type: Headline
      settings:
        levels: [1]
    - role: author
      type: Text
    - role: image
      type: Picture
      settings:
        size: 1200x600
        crop: true
    - role: teaser
      type: Richtext

# Post Text: Repeatable section with auto-generated anchors for deep linking
- name: post_text
  ingredients:
    - role: headline
      type: Headline
      settings:
        levels: [2, 3]
        anchor: from_value
    - role: text
      type: Richtext

# Post Picture: Repeatable image with responsive srcset
- name: post_picture
  ingredients:
    - role: image
      type: Picture
      settings:
        srcset: ["400x", "800x", "1200x"]
        sizes: ["(max-width: 600px) 400px", "(max-width: 900px) 800px", "1200px"]

# Blog Overview: Headline for the main blog index page
- name: blog_overview
  unique: true
  ingredients:
    - role: headline
      type: Headline
      settings:
        levels: [1]
      default: Blog

  9. Manage multiple websites with Alchemy CMS

    Alchemy supports hosting multiple websites from a single Rails application. Each site is isolated with its own domain, languages, and page trees. Sites are identified by their host name; Alchemy matches incoming requests against configured hosts to serve the appropriate content.

  10. Understand the Alchemy CMS Page model

    In Alchemy CMS, pages do not store actual content. Instead, they act as a structural tree for the website, providing unique friendly URLs and metadata (name, title, visibility, published status, and SEO attributes). The actual content is stored in 'ingredients' within 'elements' that are assigned to the page based on its page type definition.

  11. Manage downloadable files with the Alchemy Attachment Library

    The Attachment Library handles downloadable files (such as PDFs, documents, or archives) assigned to File ingredients on elements. It supports bulk uploading, tagging, and filtering by file type, tags, or upload date. A key feature is the ability to replace a file while maintaining the same record and URL.

  12. Configure page layouts for a blog and blog posts

    Define the structure of your blog index and individual posts in config/alchemy/page_layouts.yml. The blog overview page should have cache: false to ensure it reflects the latest published child pages (posts).
    # config/alchemy/page_layouts.yml
- name: blog
  unique: true
  cache: false # overview lists child pages, must reflect publish changes
  elements:
    - blog_overview
  autogenerate:
    - blog_overview

- name: blogpost
  elements:
    - post_header
    - post_text
    - post_picture
  autogenerate:
    - post_header