Skip to content

Biocaching/docbox

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

29 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Docbox 📘

Circle CI

Docbox is an open source version of Mapbox's REST API documentation system. It takes structured Markdown files and generates a friendly two-column layout with navigation, permalinks, and examples. The documentation source files that Docbox uses are friendly for documentation authors and free of presentational code: it's Markdown.

Demo documentation

Docbox is a JavaScript application written with React. The core magic is thanks to the remark Markdown parser, which enables the layout: after parsing a file into an Abstract Syntax Tree, we can move examples to the right, prose to the left, and build the navigation system.

It has a supercharged test suite. Our tests check for everything from broken links to invalid examples and structure problems: this way, the application is only concerned with output and you can proactively enforce consistency and correctness. We even extract JavaScript examples from documentation and test them with eslint

When you're ready to ship, Docbox's build task minifies JavaScript and uses React's server rendering code to make documentation indexable for search engines and viewable without JavaScript.

Docbox is a Mapbox community open source project. We built an awesome system for our REST API documentation and wanted to share it with you. Not a Mapbox product, so there's no guaranteed support and may have some rough edges.

Writing Documentation

Documentation is written as Markdown files in the content directory, and is organized by the custom/content.js file - that file requires each documentation page and puts them in order. This demo has a little bit of content - content/example.md and content/introduction.md, so that there's an example to follow.

Customization

All custom code - code that relates to brands and specifics of APIs - is in the ./custom directory. Content is custom/content.js and brand names & tweaks are in custom/index.js, with inline documentation for both.

Development

We care about the ease of writing documentation. Docbox comes with batteries included: after you npm install the project, you can run npm start and its development server, budo, will serve the website locally and update automatically.

Requirements

  • Node v4 or higher
  • NPM
  • Git

To run the site locally:

  1. Clone this repository 2. git clone https://github.com/mapbox/docbox.git
  2. npm install
  3. npm start
  4. Open http://localhost:9966/

Tests

Tests cover both the source code of Docbox as well as the content in the content/ directory.

To run tests:

  1. Clone this repository 2. git clone https://github.com/mapbox/docbox.git
  2. npm install
  3. npm test

Deployment

The npm run build command builds a bundle.js file that contains all the JavaScript code and content needed to show the site, and creates an index.html file that already contains the site content. Note that this replaces the existing index.html file, so it's best to run this only when deploying the site and to undo changes to index.html if you want to keep working on content.

  1. Clone this repository 2. git clone https://github.com/mapbox/docbox.git
  2. npm install
  3. npm run build

Props to Tripit's Slate project, which served as the inspiration for Docbox's layout. We also maintain a list of similar projects.

About

REST API documentation generator

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • CSS 81.2%
  • JavaScript 18.4%
  • HTML 0.4%