Developers

What you add to your website

Headra is hosted for you. There's no server to set up, no plugin and no build step: your website just asks the API for content.

Static HTML or Bootstrap Studio

Works on any hosting, even hosts that only accept HTML, CSS and JS uploads.

  • A public API key
  • Two script files: config.js and headra.js
  • A spot on the page for the content
  • Optional: one DNS record for your sitemap

React, Vue, Next, Nuxt or mobile

It's a plain JSON API. No SDK or library to install.

  • A public API key
  • A fetch call with the key in a header
  • At runtime or at build time for static generation
  • Optional: one DNS record for your sitemap

A static site in four steps

Or skip ahead: the starter kit is a complete working site you download from the admin, with config.js already filled in.

1

Create a public key

One click under API keys in the admin. Public keys are read-only and only ever see published content, so they're safe in website code.

config.js
window.HEADRA = {
  api: 'https://app.headracms.com',
  key: 'hcms_pub_…',
  menu: 'header',         // menu shown by Headra.chrome()
  collection: 'pages',
  richText: ['body'],     // fields rendered as HTML
};
2

Add the two scripts

Just before </body> on each page. In Bootstrap Studio, add them under Design → JavaScript, in this order.

index.html
<script src="config.js"></script>
<script src="headra.js"></script>
<script src="latest-posts.js"></script>  <!-- your code -->
3

Show the content

Put an empty element where it should appear, and fill it with a few lines. Text is escaped, images come with every size, and rich text is already cleaned.

latest-posts.js
(async () => {
  const { api, esc, image, date } = Headra;
  const { data } = await api('/api/posts', { per_page: 6 });

  document.querySelector('#latest-posts').innerHTML = data.map((post) => `
    <article class="col-md-4">
      ${image(post.fields.featured_image, 'medium')}
      <h3>${esc(post.title)}</h3>
      <p>${esc(date(post.published_at))}</p>
    </article>`).join('');
})();
4

Optional: your sitemap on your domain

Add one DNS record, enter the same address in your website's settings, and Headra serves sitemap.xml and robots.txt for your website, rebuilt whenever content changes. Nothing to upload.

DNS
api.yoursite.com   CNAME   app.headracms.com

# Then submit to Google Search Console and Bing:
https://api.yoursite.com/sitemap.xml

One-line helpers

The headra.js helper does the fiddly parts for you, so a page is a handful of lines.

api(path, params)Fetch content with your key.
esc(value)Show text safely.
image(media, size)A responsive, lazy-loaded image.
field(name, value)Render any field: rich text, galleries, links, lists.
seo(item)Page title, meta and social tags, and structured data.
track(type, slug)Count a page view. Free: it doesn't use your API allowance.
chrome()Render your header menu and footer.

Any framework

React, Vue, Next, Nuxt, Eleventy, mobile apps or your own server. Fetch at runtime, or at build time for fully static sites.

  • Paging, search and sorting
  • Filter by category, tag or any field
  • Ask for only the fields you need
  • Menus, categories, tags, authors and redirects
posts.js
const res = await fetch(
  'https://app.headracms.com/api/posts?category=news&sort=-published_at',
  { headers: { 'X-Api-Key': process.env.HEADRA_PUBLIC_KEY } },
);
const { data, meta } = await res.json();

// data[0].title, .slug, .url, .fields, .seo, .json_ld …
// meta.page, meta.total_pages

Ready to connect a website?

Get early access and you'll have a working site with the starter kit in minutes.

Get early access