Embrace Documentation

This repository hosts the source code for the Embrace documentation site.

The docs site is automatically deployed from this repository on a regular daily interval. We welcome all contributors who would like to grow knowledge and clarity regarding the Embrace mobile SDKs, dashboard, and data forwarding features. Please feel free to make a pull request to make an addition, or open an issue to make a suggestion of what might be change.

This website is built using Docusaurus, a modern static documentation generator written using React. Some specific changes to Docusaurus are noted below in Embrace Customizations.

Updating These Docs

You can make edits to these docs from within GitHub UI or by forking/cloning the repo to make edits locally.

Recommendations

For quick edits that don't require adding or reorganizing pages, you can edit the specific Markdown file from within the docs folder. Edit the file, commit your changes and make a PR.

For larger reorganization, you should follow the structure of the docs folder to see where your new pages will go. Any change to the landing page organization will be in the Categories.tsx file. Any change to the outer-most level of organization will be in the sidebars.ts file.

Local Development

You can edit and build these docs on your local machine by pulling the repo and following the instructions below. We recommend using an integrated development environment like VSCode to simultaneously edit the source files, note markdown or linking errors, and run the docs via Node.

Installation

$ npm i

This command will install all node packages and their dependencies. This command is usually optional, as the packages are prebuilt in this repository.

Start

$ npm start

This command starts a local development server and opens up a browser window. Most changes are reflected live when a file is saved, without having to restart the server.

Build

$ npm run build

This command generates static content into the build directory and can be served using any static contents hosting service. You can serve contents of that static directory using npm run serve

Embrace Customizations

Besides basic "markdown" syntax we are using these Docusaurus features:

• Admonitions for various hints/tips/warnings "callouts"
• Tabs to show code snippets for several languages or platforms. Note that tabs support synchronizing their state across multiple (for example, several sets of tabs on one page will all switch from Swift to Objective-C together if user clicks on any one).
• MDX and React to load reusable snippets of text from shared/ directory

The following are the extras we added to handle Embrace's documentation:

• @easyops-cn/docusaurus-search-local search plugin
• src/remark/embrace-sdk-version.js Remark plugin that inserts latest SDK version (from embrace.json into various code blocks), using {{ embrace_sdk_version platform="something" }} syntax.
• Snippets in shared/ that are loaded on several pages

And we customized the following:

• Various logo and titles, as well as site-wide footer in docusaurus.config.js
• Extra syntax-highlighting languages in docusaurus.config.js
• Single sidebar used site-wide in sidebars.js that also enforse some collapsed/open state
• Homepage via src/components/HomepageFeatures in src/pages/index.js
• Some styling via src/css/custom.css (for both light and dark modes)

Tips

• If you make changes to docusaurus.config.js or some other site-wide .js files you typically need to fully restart npm start process and not rely on its hot-reloading.
• The searchbox on the site is only indexed for static build and is not available via local npm start.