1. Content Structure and Files
    1. File Organization
    2. Configuration Files
    3. Customization Options
  2. Running Station
    1. Running Standalone
    2. Running With Docker
  3. Configuring the Feedback Widget

Content Structure and Files

Station requires the content served by the platform to be organized in a defined way. The platform will not start if the folder structure is not present in the content path provided during initialization.

Additionally, Station offers a lot of opportunities to customize the platform for unique needs.

This section will go through each of these areas.

File Organization

Inside the top-level folder of the content there must be the following folders:

+-- _use_cases
+-- _documentation
+-- _tutorials
+-- public
+-- config

If you wish to include API specification reference documents you should also include a _open_api folder in the top-level of your folder structure as well.

Configuration Files

All configuration files are written in YAML. The Official YAML Web Site provides instructions on YAML formatting and specifications.

There are same configuration files provided in this repository that can be used to provide a template for the configuration files for your instance of Station.

All configuration files are placed inside the /config folder.

The files required are:

In addition to the above configuration files, Station also expects the following files to be created and placed inside the /public/meta path. These files are meta icons also used in the generation of the <head> content:

Specific credentials and identification information for different third-party services can be included in the platform by placing them inside a dotenv file in the top-leve folder of the content. There is a sample .env file provided in this repository.

Customization Options

Station provides many opportunities to customize the presentation of the platform. This section will walk through each possibility.

Custom Views

Custom views can be provided that override the defaults in Station. A sample custom views folder can be found in this repository.

To provide your own custom view for a Station view place it inside /custom/views.

The file should be an ERB file. ERB, or embedded Ruby, are HTML files that combine Ruby to product dynamic content. The Ruby documentation provides detailed instructions on how to write with ERB.

Custom Landing Pages

Landing Pages are a feature of Station that enables content creators to introduce unique website pages using only YAML to create the content.

A sample landing pages folder has been provided in this repository to offer examples.

All landing pages should be placed inside /custom/landing_pages. The URL path is defined by the file path. For example, a file placed inside /custom/landing_pages/events/myevent.yml would be viewed in the browser at

Detailed instructions are available in the Contribution Guide on creating landing pages.

Custom Public Path

Custom assets, such as images and icons, can be provided in the /public folder. They then can be referenced inside custom views. For example, if the following image is added inside /public/assets/media/logos/sample_image.png then it could be referenced using ERB syntax as follows:

<%= image_tag('/assets/media/logos/sample_image.png') %>

Custom Locale Settings

Station supports internationalization for different spoken languages. Content translations can be provided inside the /custom/locales folder. A sample locales folder has been provided inside Station with examples of locale configuration files.

Running Station

Station can be run either standalone on your system or in Docker with the provided Docker image.

Running Standalone

Once you have installed Station and ran through the configurations, you can start it.

To start the gem run the following from the command line:

$ OAS_PATH=[PATH TO _open_api folder] bundle exec nexmo-developer --docs=[PATH TO DOCUMENTATION]

For example, if your documentation is at /Users/sample_user/Documents/sample_docs and your _open_api folder is at /Users/sample_user/Documents/sample_docs/_open_api then you would start nexmo-developer with the following command:

$ OAS_PATH=/Users/sample_user/Documents/sample_docs/_open_api

The OAS_PATH environment variable passed in during runtime can also be provided in the dotenv file mentioned above in the instructions.

Running With Docker

Station is available as a Docker image at nemxodev/station. You can run it from your documentation directory using the following command:

docker run -p 3000:3000 -v /path/to/docs:/docs -t nexmodev/station

Any functionality requiring a database (such as redirects or feedback) will not work using this method. For a docker-based setup that includes a database add the following docker-compose.yml file to your project:

version: "3"
    image: postgres
      - POSTGRES_USER=nexmo_developer
      - POSTGRES_DB=nexmo_developer_production
    image: nexmodev/station:latest
      - .:/docs
      - "3000:3000"
      - db
      - POSTGRES_HOST=db

After running docker-compose up, you will need to run docker-compose run web bundle exec rake db:migrate to initialise the database.

Configuring the Feedback Widget

The Feedback Widget is a fully customizable, wizard-based approach to leaving feedback. You can configure it to accept feedback from users which is both useful and actionable.

Configuring the Feedback Widget

The Feedback Widget configuration is YAML-based and can be found in the config/feedback.yml file in your documentation directory.

Note: The Feedback Widget only appears if this file is present.

Configuration involves specifying the different “Questions” you want to ask and the “Steps” you want to take in response to the answers to those questions.

The general format of this file is as follows:

title: Thanks! We love feedback!
  - question: Your documentation is great!
    sentiment: positive
      - title: We're glad you love our docs
        type: textarea
        content: |-
          We're glad you found what you are looking for!
        label: Is there anything we did particularly well?
        placeholder: Please type your feedback here
        image: "/assets/images/applause.png"
  - question: There is a problem with the documentation
    sentiment: negative
      - title: Thanks for letting us know!
        type: radiogroup
          - The documentation is missing information.
          - The documentation is unclear.
          - The documentation is incorrect.
          - There is a broken link.
      - title: What have we left out?
        type: textarea
        placeholder: Please tell us what's wrong?
        email: true
      - title: Thanks for letting us know
        type: plain
        content: |-
          We have recorded your feedback. If you have left your email address, we'll be in touch!
    - question: I need help!
        - title: What do you need help with?
          type: radiogroup
          - My account/billing.
          - The capabilities of the product.
          - Something else.
        - title: Let's get you some help!
          type: fieldset
          - type: input
            name: firstName
            label: First name
          - type: input
            name: lastName
            label: Last name
          - type: input
            name: companyName
            label: Company Name
          - type: input
            name: apiKey
            label: API Key
            hint: "(Hint: You can find this in your account dashboard)"
          - type: textarea
            name: feedback
            label: 'Please tell us how we can help you:'
            placeholder: Please leave feedback here
        - title: Thank You!
          type: plain
          content: |-
            We have recorded your feedback and will get back to you as soon as we
          image: "/assets/images/support.svg"          

Anatomy of the configuration file


The paths property defines the different “routes” that users can take through the feedback widget. It contains a sequence of question objects.


Each question object represents one choice on the front page of the wizard and drives the flow of the feedback from that point onwards. Each option is selectable using a radio button.

For example, in the configuration shown above, the front page of the wizard would show a dialog that contains the following options in a radio group:

[ ] Your documentation is great!
[ ] There is a problem with your documentation
[ ] I need help

At the point the user selects an item in this group, the feedback configured in the sentiment property is recorded. This is either positive, neutral, or negative. After that, the flow through the feedback widget depends on what is configured in the steps for that question.


The steps property is a sequence of objects that specify the route through the wizard based on the main question selected. There can be one, or multiple, steps.

Each step shows a new page of the dialog, which can be one of the following different types, depending on the type property:

Any step can capture the user’s email address so that you can get back to them about the feedback they have left. To include this field, specify email: true for the step.


The feedback captured by the wizard is stored in the database at [YOUR_SITE_URL]/admin/feedbacks. The questions the user was asked and the responses they entered are also stored, so that the users’ answers can be seen in the context of the questions you asked. So, if you change the wizard’s configuration, the users’ responses still make sense.

Integration with Orbit

Feedback can be sent to your organization’s Orbit workspace by configuring two environment variables: ORBIT_API_KEY and ORBIT_WORKSPACE_ID. The feedback sentiment (e.g. negative, positive), documentation resource URI and visitor email address is sent to the Orbit workspace for any feedback left by a visitor that provides an email address.