Code Story is able to embed Live Code views by scanning the codebase for small tokens in comments.

A live code view of the project.

The Related Files Panel provides an overview of the files involved in your note, based on the live code views you created.

Of course, you can open the code view in your favorite editor.

But you can also use the integrated editor to do small edits : click into the code and you'll transition into a full-page editor !

Defining base directories 

Before you attempt to insert live code views in your notes, it's important to make sure your project's base directories are correctly defined.

In order to display your live code views, Code Story needs to know where your codebase lives.

You can define several base directories if that makes sense, but keep in mind that defining multiple ones is just for clearer presentation : it doesn't affect how files are scanned.

For example, the sample project that comes with the Code Story documentation has two components:

  • a frontend in Meteor / javascript,
  • a backend in python.

It makes perfectly sense to define distinct code bases.

The immediate benefit is that the Related files panel makes it very clear what code source the files related to the current note belong to.

Code Story supports nested sources. For example, it's ok to define as two separate code bases a main project and a sub-project living in the file hierarchy of the main project.


Open the project settings

Open the project settings by clicking on the wrench icon in the top right of the window.


Check the code roots

Project sources are defined relatively to where the .codestory documentation bundle lives.

For this reason, it's a good idea to save the documentation at the root of your project.


Exclude the folders that don't need to be scanned

This is a critical step to keep Code Story fast and reliable

If Code Story encounters too many files during a scanning process, it will stop and complain about it :

You can raise the limit that triggers this message, but you should always first make sure that unwanted folders are correctly excluded.


Check the file types

You should also make sure the file types you want to use are defined :

Inserting code views 

Say you're writing a note describing a mechanism of your project and  you want to refer to a few lines of your code.

Let's insert a live view of it !


Click the live code view button

The live code view button

A modal dialog shows up.

The new Live Code View modal panel


Copy the token to the clipboard

You can choose a comment variant for your convenience or you can use the raw token.

You can click the Create button immediately and insert a code view with a (yet) unfound token, or you can do this after Step 4.


Insert the token into the code you want to display in the live view

Using your favorite editor, paste the token into a comment and save the file.


Optionally adjust the inspector settings

Lines before / after fields let you adjust the number of lines to display around the token.

You can use the up and down arrows to adjust those values.

The Syntax Chooser lets you pick a different syntax than the one that was automatically set.

The Show Indicator checkbox lets you display a small arrow to bring attention to the exact line of the token.

JSON files 

As you probably know, JSON specifications don't support comments.

It makes it impossible to use the tokens approach to display live views of JSON files.

Thankfully, we provide another way, currently in beta, using Pinned Files.

A Live View of a JSON File (featuring inline comments!)

In order to use a JSON file in a Live Code View you need to :


Add the JSON file to the Pinned Files


Insert a Live Code View

... but instead of using a token, follow the "JSON file ?" in the upper right corner.


Pick jour JSON file


Using the inspector, pick a keypath

Click the target icon :

A full screen JSON view editor shows up.

Click on key to select it.

The keypath is now selected.

The Live Code view is now focused on the chosen keypath.