livingdocs-sdk
The official Node.js client for Livingdocs.
This is a low-level library. If you're looking for a full-fledged use case, consider taking a look at our magazine example
Also, check out our service documentation at https://developers.livingdocs.io
Prerequisites
- Minimum Node version: 14
- Read the Changelog to get up to date
Getting started
We assume, you already have an account on https://edit.livingdocs.io
If not, create one now.
You can also check the full example in runkit, but make sure to replace the API token with your own: https://runkit.com/gabriel-hase/livingdocs-first-steps
- Install the SDK
npm install @livingdocs/node-sdk
- Get your access token from
edit.livingdocs.io
by navigating to Access Management
-> Api Tokens
![Api Tokens in Livingdocs](http://livingdocs-assets.s3.amazonaws.com/sdk/api_tokens.png)
- Get a document
const liSDK = require('@livingdocs/node-sdk')
const liClient = new liSDK.Client({
url: 'https://server.livingdocs.io',
accessToken: 'my-awesome-token'
})
const publication = await liClient.getPublication({documentId: 1})
We assume that you used the standard signup flow. This would give you a document with id 1. Of course you can change this id to any document in your project.
- Get a design
const design = await liClient.getProjectDesign()
This gets the design used in the project with the API token provided.
A special case (mostly for non-service use cases) is if you want to get a specific globally referenced design. This might not be the design used in your project.
const design = await liClient.getDesign({name: 'living-times', version: '1.0.2'})
- Create a living document
const liSDK = require('@livingdocs/node-sdk')
const livingdoc = liSDK.document.create({content: publication.content, design})
- Render a living document to HTML
livingdoc.render()
- ...or render single components
const liSDK = require('@livingdocs/node-sdk')
const html = liSDK.document.renderComponent(livingdoc.componentTree.first())
Rendering a Document
To sum up, we wrapped the whole procedure in a snippet below:
const liSDK = require('@livingdocs/node-sdk')
const liClient = new liSDK.Client({
url: 'https://server.livingdocs.io',
accessToken: 'my-awesome-token'
})
const publication = await liClient.getPublication({documentId: 1})
const design = await liClient.getProjectDesign()
const livingdoc = liSDK.document.create({content: publication.content, design})
const html = livingdoc.render()
Note: This snippet loads the latest design from your service project and uses our default image service.
Where to go from here
I don't want to use document ids
Livingdocs provides you with a homepage for each project and configurable menus.
You can set a homepage and create a menu in the Livingdocs editor (edit.livingdocs.io).
Check out the Client API reference documentation below for the respective methods to fetch the homepage or a menu from Livingdocs.
I need my own design
Currently, you can only use embedded designs in your livingdocs editor. getting started with your own design
Otherwise you can use one of the given design in the editor and adapt the rendering on your side.
For the delivery rendering you can have a local copy of our magazine design and adjust the HTML / CSS for the rendering. This means that you will write in the Livingdocs editor in our prebuilt design but render to your own custom design using the SDK.
Check out the Livingdocs magazine example frontend on how to achieve this.
I want to change the output before rendering
The Livingdocs API provides you with our Livingdocs JSON format. The SDK allows you to build a native livingdoc instance out of the JSON response. The livingdoc instance gives you many options to change the output of your rendering, e.g. skipping certain components, set global styling options or change the way images are rendered.
Check out the livingdoc reference documentation for an intro to the livingdoc API.
API Reference Documentation
const liSDK = require('@livingdocs/node-sdk')
Document API
const document = liSDK.document.create({design, content, config})
const config = {
imageServices: {
liImageProxy: {
host: 'https://server.livingdocs.io',
preferWebp: true,
backgroundImage: {
maxWidth: 2048
},
srcSet: {
defaultWidth: 1024,
widths: [2048, 1024, 620, 320],
sizes: ['100vw']
}
}
}
}
const visitedDocument = liSDK.document.visit(document, filter, visitor)
const includes = liSDK.document.getIncludes(document)
const html = liSDK.document.renderComponent(component)
const html = liSDK.document.render(document)
Client API
const liClient = new liSDK.Client({
url: 'http://localhost:3001',
accessToken: 'my-awesome-token',
proxy: 'http://path.to.proxy',
agent: new CustomHttpsAgent()
})
const [menu] = await liClient.getMenus({handle: 'main'})
const {versions} = await liClient.getDesignVersions({name: 'living-times'})
const design = await liClient.getProjectDesign({version: '1.0.2'})
const design = await liClient.getDesign({name: 'living-times', version: '1.0.2'})
const [homepagePublication] = await liClient.getPublications({homepage: true, limit: 1})
const publication = await liClient.getPublication({documentId})
const media = await liClient.getMedia({id, ids, externalId, systemName})
const publications = await liClient.search({search, categories, languages, contentTypes, fields, limit, offset})
Livingdoc Content Model API
Check out the reference docs