Published by

pen and notes
\( \def\AA{\mathbb{A}} \def\BB{\mathbb{B}} \def\CC{\mathbb{C}} \def\DD{\mathbb{D}} \def\EE{\mathbb{E}} \def\FF{\mathbb{F}} \def\NN{\mathbb{N}} \def\OO\mathbbglossterm::[O] \def\PP{\mathbb{P}} \def\QQ{\mathbb{Q}} \def\RR{\mathbb{R}} \def\ZZ{\mathbb{Z}} \def\ffp{\mathfrak{p}} \def\bold#1{\bf #1} \def\CCC{\mathcal{C}} \def\EEE{\mathcal{E}} \def\FFF{\mathcal{F}} \def\PPP{\mathcal{P}} \def\UUU{\mathcal{U}}    \newcommand{\commadots}{, \ldots, } \newcommand{\set}[1]{ \{\,#1\, \} } \newcommand{\sett}[2]{ \{\,#1\, \mid\, #2\, \} } \newcommand{\Set}[1]{ \Big\{\,#1\, \Big\} } \newcommand{\Sett}[2]{ \Big\{\,#1\, \Big\vert\; #2\, \Big\} } \newcommand{\mapright}[1]{\ \smash{ \mathop{\longrightarrow}\limits^{#1}}\ } \newcommand{\vars}[2]glossterm::[#1}_1\commadots{#1}_{#2] \newcommand{\map}{\longrightarrow} \def\rank{\mathop{rank}} \def\dim{\mathop{dim}} \def\height{\mathop{height}} \)
This notebook needs to be udpated — many improvements to Noteshare since it was written.

1. What is NoteShare? is a tool for creating and sharing online notebooks. Here are some examples:

Your Account

When you sign up for Noteshare, you get a web paged linked to your screen name. Thus John Doe, who set up his account as, has the site The public version of John’s site — whose content is available to his grandmother and everyone else — is That’s the web address to give to your family, fans, co-workers, students, etc.

Figure 1. Bird

Noteshare documents are written in Asciidoc, a markup language. "Markup" means that you add little codes to your text to structure it and shape its appearance. For example, to obtain italic text, you write _something like this_. The underscore character _ is the markup code. Boldface is done in a similar way: *Boldface*.

See the working with notebooks section of this handbook for more examples — how to make lists and charts, place hyperlinks like this article on atoms, how to place images like the one of the bird you see on the right, and even how to write mathematical formulas like \(\sqrt{a^2 + b^2}\). For still more examples, take a look at this sample document.

Technical stuff and roadmap is based on the powerful Asciidoctor text processing and rendering engine. A forthcoming update will allow you to compile a Noteshare document which you create into other formats: PDF, epub3 (electronic book), or LaTeX.

2. Working with notebooks

Screen Shot 2015 08 21 at 11.19.16 AM
Figure 2. Editing Panel

This section describes how to use the tools for creating, editing, and managing notebooks. If you click on the title of one of the notebooks listed on your home page, you will be led to a page which displays the editor control panel. It should look roughly like the control panel in Figure 1. For a short description of what a button does, mouse over it. For a longer description, click on the help tool question.

In what follows, we group the buttons by function — creating a notebook, creating a section, adding an image, etc. The first two are essential, while the remaining ones can be studied at your leisure.

2.1. Create a notebook

To create a notebook and edit its first section, you will need to know how to use just four buttons.


Go the home page and click on new_document to create a document. Fill out the form and press Create. You will be led a page with the controls as displayed in the figure elow.


The controls for editing a document are displayed in Figure 1 above. Click on edit to edit the current section.


If you are editing text for the current section, click on Screen_Shot_2015-08-21_at_8.39.38_AM to update and save it. The key command Ctrl-U has the same effect.


Click on Screen_Shot_2015-08-21_at_8.42.01_AM to exit the editor window without saving. The key command Ctrl-X has the same effect.

2.2. Create a new section

To create a new section of a notebook, then publish or share it, use the buttons listed below.

Screen Shot 2015 08 21 at 11.19.16 AM
New section

Click on new and fill out the form. In the form there is a check box labeled "Attach PDF". Check it if you want to upload a PDF file, and then follow directoins.


Click on publish to make the current section public. Click on it again to make it private. If the section is public, the background is green. Anyone can view a public section. Cllick on unlock to make all sections of the current notebook public. Click on it again to make all sections private.


Click on share to share a section with someone by email.

Mouse over a button in the Editing Panel to view a short description of what it does.

2.3. Images

Upload image

Click on image to upload an image. Fill out the form, choose the image, then press Upload. When the upload is complete, note the ID of the image. For instance, if the ID is 632, you can place an image in your document with image ::632[] or image ::632[width=200].

For audio, use the same button but write the link as audio ::632[]. For video it is best to link to YouTube or vimeo. See adding video in this manual.

2.4. Manage notebook

Tags, Summary

Click on tag to edit the section summary or its search tags.

Change title

Click on gears to change the title of a notebook or to edit its search tags.

Change order of sections

Click on toc to change the order of the section of a notebook.

Delete section

Click on trash to delete a section. This operation cannot be undone. You will be asked to confirm your choice.

2.5. Collaboration


If the author of a document allows comments on it, the comment tool comment will be displayed. Click on it to add a comment. The comment must be of the form


To ensure that your comment will be posted, do not modify the text upon which you comment. Your user name and the date will be included with the comment.


Click on checkout to check a section out. Click it again to check the section back in. When a section is checked out, only the person to whom it is checked out can edit it. This feature is useful for collaborative writing and editing projects.

Make includable:

When a section is "includable", part or all of a section may be included in another document. Click on toggle_inclusion to permit inclusion. Click it again to forbid inclusion. A section that is includable displays hte include tool with a light green background. See the May, 2015 newsletter to see how this feature works.

2.6. Export


Click on download to export an entire notebook. See the xJune, 2015 Newsletter for details on how this is done and for a description of what the download includes.

3. Markup Basics

In this section we go over the markup codes that you will most likely need when starting out — italic, bold, highlighted and strikethough text, lists, tables, references to web pages, images, and structuring a document into sections, subsections, and so on. We then discuss block constructs — quotations, verse, code, verbatim, etc.

In each case, we give references to more comprehensive sources.

3.1. First things first

Italic text

He shouted, this is very important!

He shouted, _this is very important!_
Bold text

He shouted, this is very important!

He shouted,  *this is very important!*
Highlighted text

Psychologists believe that marking up selected parts of a long text improves comprehension and memory. Sometimes the use of color can differentiate different kinds of text.


Ms. Grundy made the following correction: "Dear teacher. I ain’t gonna like this class. Can I be excused?"

Numbered Lists

You write a numbered list of errands:

  1. Get groceries

  2. Put gas in the car

  3. Drop a package off at Fedex

Here is the marked-up text:

. Get groceries
. Put gas in the car
. Drop a package off at Fedex
Bulleted lists

You are writings an outline for a class presentation:

  • Atoms are the building blocks of matter

  • Atoms are very, very small

  • The idea goes back to Democritus, around 500 BC

  • We now know that atoms can be broken down into smaller particles

Here is the marked up text:

* Atoms are the building blocks of matter
* Atoms are very, very small
* The idea goes back to Democritus, around 500 BC
* We now know that atoms can be broken down
into smaller particles

You want to link to an article about Niels Bohr

Here is the marked-up text:

You want to link to an article about[Niels Bohr]

Just paste in the link and follow it by a few words enclosed in brackets. Some times the links are so long that you have to choose the Wide option in the Edit menu.


Noteshare documents can display media: images, audio, and text. The image below was inserted using the markup

image ::460[]

Here 460 is the ID number of the image. See XXX for more information about uploading media and placing them in your document.


3.2. Sections

Section, subsections, etc., are indicated like this:

 == Top level section

 Blah, blah

 === Subsection

 Fee, fie, fo fum!

 ==== Subsection

 Ho ho ho!

 ===== Subsubsubsection

 The end!

Sections can be numbered or un-numbered.

Put the code :numbered: in your document to turn numbering on, put :!numbered: to turn it off.

3.3. Blocks

Blocks are used for quotations, poetry, computer code, and much more. The general form of a one-paragraph block is


The general form of a several-paragraph block is




We illustrate this construction below.

3.3.1. Verse

Poem — one paragraph
’Twas brillig, and the slithy toves
      Did gyre and gimble in the wabe:
All mimsy were the borogoves,
      And the mome raths outgrabe.
’Twas brillig, and the slithy toves
      Did gyre and gimble in the wabe:
All mimsy were the borogoves,
      And the mome raths outgrabe.
Poem — several paragraphs
’Twas brillig, and the slithy toves
      Did gyre and gimble in the wabe:
All mimsy were the borogoves,
      And the mome raths outgrabe.

“Beware the Jabberwock, my son!
      The jaws that bite, the claws that catch!
Beware the Jubjub bird, and shun
      The frumious Bandersnatch!”
’Twas brillig, and the slithy toves
      Did gyre and gimble in the wabe:
All mimsy were the borogoves,
      And the mome raths outgrabe.

“Beware the Jabberwock, my son!
      The jaws that bite, the claws that catch!
Beware the Jubjub bird, and shun
      The frumious Bandersnatch!”

3.3.2. Quotations

A man who dares to waste one hour of time has not discovered the value of life.
— Charkes Darwin
The Autobiography of Charles Darwin
[quote, Charkes Darwin, The Autobiography of Charles Darwin, 1809–82]
A man who dares to waste one hour of time has
not discovered the value of life.

3.3.3. Code

Below is a a block of code; note that indentation is preserved:

sum = 0.0
for k in range(1,100):
  sum = sum + 1.0/k
[source, python]
sum = 0.0
for k in range(1,100):
  sum = sum + 1.0/k

3.4. Basic tables


one dozen


twelve pounds


three quarts

The source code
| Eggs | one dozen
| Potatoes | nine pounds
| Milks | three quarts

For more, see the tables section of this manual.

4. Getting Started Guide

Each section of this Getting Started Guide is a self-contained example of how Noteshare is used in different settings. The best procedure is to take a look at the section which is relevant to your needs, then choose Source from the View menu. so as to compare the source and rendered text.

4.1. Plain text and a little more

Just begin typing like you do an email. Don’t worry about extra spaces, line breaks, etc. To start a new paragraph, just put in a pair of blank lines.

If you want to emphasize something, write this:

   _emphasize something_

If want more emphasis, do this:

  *more emphasis*

Those extra little symbols you added, _ and *, are markup symbols.

4.2. A Document with Sections

The structure of a document with sections is like this

 == Section 1
 == Section 2
 === Section 2.1
 === Section 2.3
 ==== Section 2.3.1
 ==== Section 2.3.2
 == Section 3

That’s all there is to it! That is also why every part of a Noteshare document begins with == Blah blah, === Blah blah, etc.

If you want your sections to be numbered, put the text :numbered: before where the numbering starts. To turn off automatic numbering, say :!numbered:

Because equal signs at the left margin are used for sectioning a document, be careful about where you put them. A space at the left margin followed by one or more equal signs will not confuse Noteshare.
Choose Source from the View menu to compare the source and rendered text of this section. Choose Standard to return to the normal view.

4.3. A Problem Set

  1. What is the population of the United States in square km?

  2. What is the area of the United States?

  3. What is the population density of the United States in persons per square km?


  1. Population by country (Wikipedia)

  2. Area by country (Wikipedia)

4.3.1. Clickable items

Click on the blue text to reveal what it is hiding. Click again to hide the text so revealed.

  1. What is the population of the United States in square km?

    Google it!
  2. What is the area of the United States?

  3. What is the population density of the United States in persons per square km?

    Divide the number obtained in (1) by that obtained in (2)
  4. What is the area of Washington State?

    Hint 1
    Ask the governor!
    Hint 2
    Google it!!
Another good place to choose Source from the View menu. You will see how this page was made.

4.4. Mathematics

Use standard LaTeX for mathematical formulas. Thus \(a^2 + b^2 = c^2\) is rendered from $ a^2 + b^2 = c^2 $ and \[ \int_0^1 x^n dx = \frac{1}{n+1} \] is rendered from

   \int_0^1 x^n dx = \frac{1}{n+1}

For more information about mathematical notation, see the Asciidoc-LaTeX Manual.

4.5. Math Homework

  1. Expand \((a+b)^2\).

    \(a^2 + 2ab + b^2\)
  2. Factor the number 510510.

    Use trial division
    \(2\cdot 3\cdot 5\cdot 7\cdot 11\cdot 13\)

4.6. Chemistry

Wrtie formulas like \(\ce{ Fe2O3 }\) using the chem macro: chem::[Fe2O3]

Fro displayed formulas and reactions like

\[\ce{2Fe2O3 + 3C → 4Fe + 3CO2}\] (1)

use the corresponding block macro:

2Fe2O3 + 3C -> 4Fe + 3CO2

For more informaton, see xAsciidoctor-LaTeX Manual

To publish poetry here, use the [verse] block. (Choose Source from the View menu to see how it is done).

4.7. Poetry

Twas brillig, and the slithey toves
Did gyre and gimble in the wabe:
All mimsy were the borogroves,
And the mome raths outgrabe.

"Beware the Jabberwock, my son!
The jaws that bite, the claws that catch!
Beware the Jubjub bird, and shun
The frumious Bandersnatch!"

He took his vorpal sword in hand;
Long time the manxome foe he sought -
So rested he by the Tumtum tree,
And stood awhile in thought.

And, as in uffish thought he stood,
The Jabberwock, with eyes of flame,
Came wiffling through the tulgey wood,
And burbled as it came.

One, two! One, two!
And through and through
The vorpal blade went snicker-snack!
He left it dead, and with its head
He came galumphing back.

"And hast thou slain the Jabberwock?
Come to my arms, my beamish boy!
O frabjous day! Callooh, Callay!"
He chortled in his joy. '

Twas brillig, and the slithey toves
Did gyre and gimble in the wabe:
All mimsy were the borogroves,
And the mome raths outgrabe.
 — Lewis Carroll

5. The menus

On the right is the Menu bar selector. It has five buttons. Four are used to select they way in which Noteshare is used — browser notebooks, read a notebook, write new material, upload and manage media. The fifth is a hotlist of active notebooks.

Screenshot 2015 05 24 14.33.13
  • Browse: press this to search for notebooks or to search for words within notebooks.

  • Read: press to read a notebook

  • Write: use to create the text of a new note, or to edit the text of an old one.

  • Media: Use to add or search for images, audio files, videos.

  • Hotlist: Show the most recent courses that you have pinned.

5.1. Browse menubar

Screenshot 2015 05 24 15.31.56
  • On the left side is the Noteshare menu, with three items:


    contact info, etc.


    change password

    Edit site

    change home page info page

  • To the right are two search fields. Search for words searches the entire Noteshare site for keywords and brings up a list of sections of notebooks in which they appear. Search for notebooks searches for whole notebooks.

  • On the right side is the Home menu with these items:


    help on various topics


    a list of recently viewed notebooks and a collection of tools.


    a page to log into


    a view of your home page as others see it


    the "back page", with useful information. You can customize this page.


    selected Noteshare content.


    bl adi dah!

5.2. Read menubar

Screenshot 2015 05 24 15.28.45

The "Read" menubar is like the "Browse" menubar, except that it has an item with arrows for moving to the previous or next lesson, and it has a View menu for selecting how you wish to view a section of the current notebook. The options are


View main text, aside, and table of contents (TOC). All elements scrollable.


Display main text only


View both the main text and the "aside," or notes,


Display a view of the current section suitable for printing.


Display main text and its source.


Display all sections compiled into a single "web page"


Display LaTex version of notebook.

5.3. Write menubar

Screenshot 2015 05 24 15.29.23

The Write menu bar is like the Browse menu bar except that it has three additional menus: Edit,New, and Tools

Edit menu

Edit main content


Edit main content, wide view


Edit aside


Edit capsule, tags, settings for section


Edit document attributes, e.g., sections to compile, tex macros, etc

New menu

The default: create a new section,


Attach a PDF file.


Upload and image, audio, or video file.

Tools menu

Show the table of contents.


Compile all sections into a single file — that is, compile the notebook.


Compile a complete archive of notebook: .adoc files, .html and `.tex`versions, then download it. Same as pressing the "A" button in the edit panel.

5.4. Media menubar

Screenshot 2015 05 24 15.29.46

Like the Browse menubar, but with three additional elements:


Press to upload a new image.


Display a new set of random images.

50 of 593

Shows how many media files out of the total are displayed.

6. Creating notes and notebooks

In this section we learn how to create a new note, edit it, and save it.

Open a new tab in your browser, and open the NoteShare handbook in the new tab.

6.1. Creating a Note

  • Click on "New" in the upper left of this page (see image on right). This will take you to a new window where you will see two "panes", one pinkish, the other yellowish. The pinkish one is where you type in new text.

  • Type "== Second Note" at the very top of the pinkish (source) window. You have just set the title for the note.

  • Skip down a few lines and write something.

  • Press the blue "update" button (bottom of screen), or type control-U. You should see your "rendered" text in the right-hand pane.

  • Finally, press the blue "exit" button. With this button you exit the editor. Pushing this button does NOT save your work.

6.2. Editing a Note

  • Click the "edit" link in the upper left of the screen.

  • You are now in the editor.

    • The "source" text is on the left in the yellowish window pane, the "rendered" text is on the right, in the blueish window pane

    • Start typing in the "source text" like you would in an email. Paragraphs start right at the left margin and are separated by blank lines.

    • Click the blue "update" button (bottom), or type control-U to update the rendered text and save the source text.

    • Click the blue "exit" button to go back from where you came, or type control-X.

    • Warning: Pressing exit does not save your work.

  • Soon you will have the hang of it.

6.3. Markup 102

You have probably noticed some funny little symbols in the source text. Those are "markup" codes. They affect the structure and presentation of the content that you write. For example, here is some bold text. And here is some italic text. We wrote them this way in the source window: *bold text* _italic text_

To learn how markup works, use reverse-engineering: compare the source and rendered text. Do this by choosing Source in the View menu. You will see the source text and rendered text in side-by-side windows.

There are many markup languages. We are using asciidoc markup. It can be read by both humans (us!) and by computers. We create the content and the computer uses the Asciidoctor program to translate our content into web pages, a pdf file, or an electronic book With markup, what an author writes can be published in many formats without additional work.

Our motto: Write once, use many.

  • Advantages of markup. You can create good-looking, well structured documents more quickly and with better focus than with a WYSIWYG editor. You keep you eyes on what you are typing, and your mind on the text you are creating — no breaks in thought to find the mouse or the menu item to click, no struggles with formatting.

  • Disadvantages of markup. You have to learn a few new things, as you do with any tool. The good news: most writing requires a small subset of Asciidoctor’s versatile and powerful toolset.

In this Handbook, we concentrate on the basics of Asciidoc markup, If you find you need more than is in the Handbook, please consult the documentation at

6.3.1. Markup Shortlist

You can do a great deal of writing with just little markup. Below is a short list of markup codes.

  1. Use *...* for bold text.

  2. Use _..._ for italic text.

  3. Put a dot at the left margin, then a space, then your text for a numbered list item. Look at the source for this text to see what I mean. (Click on Source in the View menu).

  4. Use an asterisk (*) instead of a space for bulleted lists.

  5. Use == TITLE for the title of your note. This text should go at the very top of the source at the left margin.

  6. Use === SUBTITLE for subtitles.

  7. Put the code :numbered: in your text to automatically number sections, subsections, etc. Everything after this code will be numbered. Say :!numbered: to turn off automatic numbering.

See how far you can get with these seven pieces of markup code!

6.4. Creating a notebook

  1. Click on *Home*in the menu bar.

  2. Click on New Notebook — right-hand column below Tools & Resources.

6.5. Editing tips

6.5.1. Order of sections


You can change the order of the sections. While in edit mode, push the TOC (Table Of Contents) button. This will transport you to a screen like the one you see below. Find the section you want to move, type the code for its destination in the corresponding box, and press the return key. For example, if you want section 3 to be where section 2 is, type "2" in the box to the right of "Basic Algebraic Geometry." To put section 3.2 where section 3.1 is, type "3.1" in the box to the right of "Projective Space".

Screenshot 2015 03 16 08.46.57

6.5.2. Numbering

To number the sections of a note, put this text: :sectnums: in the text before the numbering is supposed to begin. To turn off automatic numbering, put :!sectnums:

6.5.3. Table of contents

In the standard view mode (View > Standard), a table of contents is displayed.

6.6. Adding an image

sower with setting sun 1888 3

6.6.1. Adding images

It is easy to add images to Noteshare.

  1. Select the Media tab (upper right of menu bar).

  2. Select Upload and follow directions to upload the file from your computer.

  3. When the upload is complete, you will see the image in NoteShare. The image had an ID number, say, 198.

  4. Put this line of text in your note: IMAGE::198[width=600]

You will see the image below in your note. It occupies a space 600 pixels wide.

sower with setting sun 1888 3

6.6.2. Options

Notice that the Van Gogh image appeared twice — once as a small image on the upper right, once as a large image. The small image was "floated" like this: IMAGE::198[width=200, float=right]. Some other options: align=left, align=center, align=right.

6.6.3. Caption

Below is an image with a caption. Here is the source:

IMAGE::456[width=300, align=left]
Figure 3. Bluejay

An below is a center-aligned image with center-aligned text. Here is the source:

.King parrot
IMAGE::463[width=300, align=center]
king parrot sep06
Figure 4. King parrot

6.6.4. The Media Library

When you uploaded your file, it was stored in Noteshare’s media library. Uploaded files can be marked as public or private. Public files, like the one with ID 198, can be seen and used by anyone.

You can browse the media library to find images for your notebooks. Search by ID or by keyword, or press the "random" button.

6.7. Adding audio

Adding audio is much like adding an image, except that you use the audio tag instead of image. Here is an example:

Chopin: Nocturne in C# minor

And here is the source text:

.Chopin: Nocturne in C# minor

6.8. Adding video

Video, both uploaded and from YouTube, or Vimeo can be inserted into Noteshare documents.

6.8.1. Uploading videos

Video can be uploaded and inserted into your notes in much the same way as images. The main difference is that you say video instead of image. Below is an example. We inserted it this way: VIDEO::104[width=400]

The video above was generated using the Processing. computer language.

Not all browsers support all video formats.

6.8.2. YouTube

To insert a Youtube video, you need its embed code, e.g. EsTgr-n53Ow?. Then you can insert like this


6.8.3. Vimeo

Use VIDEO::111593305[vimeo]

6.9. Adding PDF files


Adding a PDF file to your notebook is a four-step process:

  1. Look at the upper left of the screen. You will see this:

    Screen Shot 2014 11 14 at 6.52.37 PM

    Choose New PDF

  2. A form comes up. Put in a title for your PDF file. The rest is optional. Then press SAVE.

  3. A new page comes up with the title you entered and a link Attach PDF File. Press this link.

  4. A form that comes up that asks you to load your PDF file. Select Choose PDF, browse your computer for the PDF file, then press Upload.


6.10. Diagrams

We are studying some options for adding diagrams. See this news article and Asciidoctor-diagram.

digraph g {
    a -> b
    b -> c
    c -> d
    d -> a

7. Tables

7.1. A simple table


one dozen


twelve pounds


three quarts

The source code
| Eggs | one dozen
| Potatoes | nine pounds
| Milks | three quarts

7.2. A formatted table






9 lb




3 quarts



The source code
| Eggs | 12 | 0.56 | $6.72
| Potatoes | 9 lb | 0.45 | $4.05
| Milks | 3 quarts | 1.89 | $5.67

7.3. A table with a header

Description Quantity Unit Price Price






9 lb




3 quarts



The source code
[cols="<,^,>,>", options=header]
| Description | Quantity | Unit Price | Price
| Eggs | 12 | 0.56 | $6.72
| Potatoes | 9 lb | 0.45 | $4.05
| Milk | 3 quarts | 1.89 | $5.67
Description Quantity Unit Price Price







9 lb




3 quarts



The source code
[cols="<,^,>,>", options="header,footer"]
| Description | Quantity | Unit Price | Price
| Eggs | 12 | 0.56 | $6.72
| Potatoes | 9 lb |  0.45 | $4.05
| Milk | 3 quarts | 1.89 | $5.67
|   |  |   |$16.44

8. Cross references

8.1. References within a note

To make a reference to a section, subsection, etc. of a single "note" of a notebook, enclose the verbatim text of the section name in double angle brackets, e.g., << References within Noteshare >> — but with no spaces after << or before >>. This will make a link to subsection like

  === References within Noteshare

Parts of a note can also be labeled and referred to, At the bottom of this section there is some text about the The Internet. Here is the text of the reference:


And here is the text referred to:

  .The Internet
  The world-wide web is a wild and woolly place.

The text .The Internet provides a title, while [[wooly]] provides a label. We use that label to make the reference.

8.2. References within Noteshare

Here is a reference to another note in the current notebook: adding an image. And here is how the reference is made.

xlink::520[Working with Images]

All you need is the ID number of the note. To find the ID, look the lower right of the screen. You will see the text 56:571. Here 56 is the ID number of this notebook, and 571 is the ID number of this section. Thus one could write

xlink::571[Cross reference]
Reference to a note in another notebook are made in the same way as one makes a reference to a note in the current notebook. Thus the link xlink::260[Lightning and Earthquakes], rendered as lightning and earthquakes, refers to a note in a book of Physics notes.

8.3. References to a web page

To make a reference to a web page, imitate this model:[Tree of Life]

Here is an example of the model in action:

The Tree of Life web site shows the evolutionary relationships between different life forms.

The technique used to refer to an external web page also works to refer to a pages in Noteshare. Thus one can say

  The article[HO]
  demonstrates a simulation of a mass-spring system.

in order to obtain this:

The article HO demonstrates a simulation of a mass-spring system.

For this you need to know the public URL of the noteshare page. To find it click on SA (section attribute) in the main edit window. You will see it displayed on the top right.

8.4. References to something inside a web page

Let’s suppose that we want to refer to the table of energies found at Physics Notebook, Tables. We can do this[Table
  of Energies]

to obtain this:

For this you need to know the ID of the table (if it has one). If you are the author, that is easy. You look back at the source text, which reads

  [format="csv", options="header", ...]
  Quantity, Value
  Thermal motion at room temp, 0.04 ev

There you see that"energies" was set as the ID, or label. If you are not the author, there is a geeky solution. Use View Source in you browser and search for the title, which in this case is "Energies". Look for

<table id="energies" …​

The value of the id attribute is energies, and this is what you want.

8.4.1. Demonstration text below

This text is purely for demonstration purposes:

The Internet

The world-wide web is a wild and woolly place.

9. Mathematics

You can --include-- complex mathematical text in Noteshare documents using standard LaTeX syntax. LaTeX can also be used for chemical formulas and reactions.

9.1. Syntax

Begin by putting the code :latex: somewhere in your text. Then you can use the traditional delimiters $…​ $ and


Thus for of the Pythagorean theorem, \(a^2 + b^2 = c^2\), you write $a^2 + b^2 = c^2 $ and for the same formula displayed, you write

    a^2 + b^2 = c^2.

With LaTeX, formulas can be quite complex, e.g., \[ \int_0^\infty e^{-x} dx = 1 \] Here is the source code:

    \int_0^\infty e^{-x} dx = 1

See: examples

9.2. Defining macros

To define TeX macros in the text of a document, imitate this example:

\newcommand{\sett}[2]{ \{\,#1\, \mid\, #2\, \} }
\( \def\QQ{\mathbb{Q}} \def\ZZ{\mathbb{Z}} \newcommand{\sett}[2]{ \{\,#1\, \mid\, #2\, \} } \)

Then you say

$ \QQ = \sett{a/b}{a, b \in \ZZ, \ b \ne 0} $

to get

\( \QQ = \sett{a/b}{a, b \in \ZZ, \ b \ne 0} \).

9.2.1. Notebook Macros


It is usually more convenient to define macros in such a way that they can be used for an entire noteobook. To do this, put tex like that below in the Notebook Attributes field. To so this, go to the main edit window and press the button NA.

\newcommand{\sett}[2]{ \{\,#1\, \mid\, #2\, \} }

9.3. Examples

9.3.1. Algebra

  • Laws of exponents: \( (a^3)^4 = a^{12} \) .

       (a^3)^4 = a^{12}
  • Binomial formula: \( (a + b)^3 = a^3 + 3a^2b + 3ab^2 + c^3 \) .

       (a + b)^3 = a^3 + 3a^2b + 3ab^2 + c^3
  • Rational function \[ f(x) = \frac{9x + 2y}{3x - 4y} \]

    f(x) = \frac{9x + 2y}{3x - 4y}

9.3.2. Calculus

  • Sequences: \( \lim_{n\to\infty} a_n = \pi \).

       \lim_{n\to\infty} a_n = \pi
  • Sums: \[ \sum_{n=0}^\infty \frac{1}{n^2} = \frac{\pi^2}{6} \]

     \sum_{n=0}{n\to\infty} \frac{1}{n^2}
          = \frac{\pi^2}{6}
  • Integrals: \[ \int_0^\infty e^{-x}\, dx = 1 \]

  f(x) =  \int_{n=0}^\infty e^{-x}\, dx } = 1
  • Derivatives: If \( f(x) = x^n\) , then \[ \frac{df}{dx} = nx^{n-1} \]

   If   $  f(x) = x^n $ ,
  then  \[ \frac{df}{dx} = nx^{n-1} \]
  • Partial derivatives: \[ \frac{\partial^2 f}{\partial x \partial y} = \frac{\partial^2 f}{\partial y \partial x} \]

   \frac{\partial^2 f}{\partial x \partial y} =
       \frac{\partial^2 f}{\partial y \partial x}

9.3.3. Linear Algebra

  • Matrices \[ M = \left[ \begin{array}{ c c } 1 & 2 \\ 3 & 4 \end{array} \right] \]

   M =
       \begin{array}{ c c }
        1 & 2 \\
        3 & 4
     \end{array} \right]

9.3.4. Equation environment

Here is the equation environment with a label pythag1 for cross-references. When there is a cross-reference, an automatically generated equation number is displayed. A reference to the equation looks like this (1) and is written like this:


Here is the rendered equation:

  a^2 + b^2  = c^2
\[ a^2 + b^2 = c^2 \] (1)

Here is another equation:

\[ x^3 + y^3 = z^3 \]

which was written like this:

x^3 + y^3  = z^3

Since no label (id) for cross-referencing is present, no equation number is displayed. If you go back later and put in a label, aka id, the equation number will be displayed.

9.3.5. Equation align environment

Like the equation environment, but displays multiple lines. Thus

  a + b &= b + a \\
  ab &= ba

renders as

\[\begin{split} a + b &= b + a \\ ab &= ba \end{split}\]

Because no label was given, no equation number was displayed. But for the quaternions (2) we write

    ij &= -ji \\
    ik &= -ki \\
    jk & = -kj

which renders as

\[\begin{split} ij &= -ji \\ ik &= -ki \\ jk & = -kj \end{split}\] (2)

We made our reference (2) like this

This fake article shows how one can write a real mathematics article in Noteshare. There are environment for theorems, equations, etc.

9.4. Sample Article

\( %% Blackboard bold \def\NN{\mathbb{N}} \def\QQ{\mathbb{Q}} \def\RR{\mathbb{R}} \def\ZZ{\mathbb{Z}} %% Arrows, sets, etc. \newcommand{\set}[1]{ \{\,#1\, \} } \newcommand{\sett}[2]{ \{\,#1\, \mid\, #2\, \} } \newcommand{\Set}[1]{ \Big\{\,#1\, \Big\} } \newcommand{\Sett}[2]{ \Big\{\,#1\, \Big\vert\; #2\, \Big\} } \newcommand{\mapright}[1]{\ \smash{ \mathop{\longrightarrow}\limits^{#1}}\ } \)

This "article" is a demonstration of how one can write mathematics in Noteshare. Use arbitrary LaTeX inside the traditional dollar sign, bracket delimiters, and a form of the LaTeX environment. Equation numbering and cross-referencing is supported, as is the numbered theorem environment.[1]

Be sure to choose Source from the View menu to see how this article was written.

Observe the footnote reference in the previous paragraph. The footnote is *way*at the bottom. However, you can click on it it reference it.

9.4.1. Pythagorean triples

One of the first real pieces of mathematics we learn is this:

Theorem 1.
Let \(a\), \(b\), and \(c\) be the sides of a right triangle, where \(c\) is the hypotenuse. Then \(a^2 + b^2 = c^2\).

The Pythagorean theorem suggests an equation,

\[ x^2 + y^2 = z^2 \] (3)

If we demand that the unknowns be integers, then this is a Diophantine equation. We all know one solution, to equation (3) the 3-4-5 triangle. However, there are many more, in fact, infinitely many. One way of generating more solutions is to rescale existing ones. Thus 6-8-10 is a solution. However, what is interesting is that there are infinitely many dissimilar solutions. One is 5-12-13. Quite remarkably, there is a clay tablet (Plympton 322) from Mesopotamia, dated to about 1800 BC, that contains a list of 15 such "Pythagorean triples." See Wikipedia.

It is unlikely that the Babylonian mathematicians, despite their sophistication and skill, knew that equation (3) has infinitely many solutions. This fact is equivalent to the statement that the unit circle centered at the origin has infinitely many points with rational coordinates.

For more information on Pythagorean triplets, see Wikipedia.

9.4.2. Another result from ancient times

Theorem 2.
There are infinitely many primes.

Suppose that there are only finitely many primes, say \(p_1, p_2, \ldots, p_N\). Let

\[ Q = p_1p_2 \cdots p_N + 1 \] (4)

This number is is greater than the greatest prime, \(p_N\). Therefore it is composite, and therefore it is divisible by \(p_i\) for some \(i\). But the remainder of \(Q\) upon division by \(p_i\) is 1, a contradiction. Q.E.D.

9.4.3. The work of Fermat

Let us consider Theorem 1 once again. Pierre Fermat asked whether this family of Diophantine equations \(x^d + y^d = z^d\), where parameter \(d\) is greater than two, have any other than the obvious solutions, e.g., \(x, y, z = 1, 0 ,1\) where one variable is zero. Fermat conjectured that the answer was no, and he wrote in the margin of Diophantus' treatise that he had a marvelous proof of this fact, alas, too long to fit int he space available. More than 300 years later, Andrew Wiles, using techniques developed only in the twentieth century, gave a proof of the theorem of Fermat.

9.4.4. The work of Georg Cantor

Georg Cantor introduced the notion of set, e.g.,

\[ \NN = \set{ \text{integers} } = \set{ 1, 2, 3, \ldots } \] (5)

Story to be continued …​

However, let’s check that our cross-references work. We learned about the Pythagorean formula (3), and the number of solutions it has in Theorem Theorem 1. We also learned in Theorem Theorem 2 that prime numbers are quite abundant in Nature: there are infinitely many of them. Our last, incomplete section, featuring the set of integers (5), is devoted to the work of Georg Cantor.

10. Chemistry

Chemical formulas can be written in LaTeX using the chem environment, e.g.,

\[\ce{2Fe2O3 + 3C → 4Fe + 3CO2}\] (2)

Here is the source text:

  2Fe2O3 + 3C -> 4Fe + 3CO2}

For in-line formulas, e.g., \(\ce{ 2H2 + O2 → 2H2O }\), one writes

  chem::[2H2 + O2 -> 2H2O]

10.1. Examples


\(\ce{ SO4^2- }\)


\(\ce{ ^{227}_{90}Th+ }\)

chem::[\(\ce{ A\bond{-}B\bond{=}C\bond{#}D }\)

\(\ce{ A\bond{-}B\bond{=}C\bond{#}D }\)

chem::[CO2 + C → 2CO`

\(\ce{ CO2 + C → 2CO }\)

And here is barium sulfate!

chem::[SO4^2- + Ba^2+ → BaSO4 v] ⇒ \(\ce{ SO4^2- + Ba^2+ → BaSO4 v }\)

These examples follow The chem environments rely on the mhchem macro package by Martin Hensel. See the references.

10.2. Structural formulas

For structural formulas, e.g. sucrose, \(\ce{C12H22O11}\), one can insert an image:


We did this using the code

  IMAGE::105[Sucrose,200,200, align=center]

For more information, see adding an image.

10.3. References

The mchem bundle, by Martin Hensel

11. Printing

Print a section

Choose Print from the View menu. this will give you printable version.

Print a notebook

Choose Compiled in the View menu. This will compile the entire notebook in a form suitable for printing from you browser.

12. Sharing your work

Let’s imagine that your screen name is, and that you wish to share the public content of your Noteshare web site with your grandmother, now aged 103. You send her this link:

You can also share notebooks and sections of notebooks. The easiest way to do this is to press the Share link in the main document view. It will bring up a blank email message with links to the current note and notebook.

Here is what the links for this note look like:

The public links for notebooks and sections of notebooks are also available from the main editor control panel. Press NA (Notebook Attributes) for the public link of the notebook. Press SA (Section Attributes) for the public link of the section.

13. Exporting a notebook

Press the A button in the main edit view and follow directions. An archive of your notebook will be downloaded to your computer as a .zip file. The archive contains

  • A master document in three formas: .adoc, .html, and .tex (LaTeX). The latter is experimental.

  • Individual .adoc files in the folder text.

  • All image and other media files in the folder images.

  • A file manifest.adoc which you can run through asciidoctor and which references the files in text and`images`to build either an .html filw or a `.tex`file

See this article for more details.

14. Collaboration

If you are working on a notebook with one or more co-authors, you should form a writer’s group on Noteshare and add your document this group. Then any member of the group can create and edit sections of the notebook.

Any member of a writer’s group can check out a section. This allows an author to freely make changes without having to worry that they may be lost or garbled by the actions of another author.

When you set up your Noteshare account, a group with same name as your screen name was set up as well. Check for it in the right-hand column of your home page. It is a link which you can click on to manage your group.

14.1. Check-in and check-out


If you are working with a group of co-authors, you can check a section out so that others do not inadvertently edit it while you are editing it. To check out a section, press the CO. button in the left column of the main editor page. When a section is checked, this button is red. Press it again to to check it back in.

14.2. Managing Groups

For the moment, groups other than the default grouop your account came with are created by request:

Every group has an owner. The owner can add and delete both users and notebooks, and can also set properties of notebooks. Deleting a notebook only removes it from that group. It does not destroy the notebook.

A document (Notebook) can be readable, writeable, or both. A group can have a mix of documents of different types — some could be read-only, while others could be both readable and writeable.

A document can be part of any number of groups.

14.2.1. The Group List

A list of all groups that you belong to is displayed in the right-had pane of the Home. Click on the name of a group for more detail. You will teleport to a page with two lists: the notebooks attached that group, and the members of the group.


You may comment on a document if the author of that document has given permission to do so. When a document has comments, the link Comments will appear in the left sidebar. Press this link to display or hide comments.

14.3.1. Making comments

In that case you will notice two buttons, Comment and Side comment in the the upper left of the main document window. Pressing one of these buttons will bring up the comment editor.

Write your comments in the form given below in the comment editor, then press the blue comment or side comment button.

  This is a comment. Nice day, isn't it?

If the comment is accepted, it will look like the one below. If you don’t see the comment, press the Comments link in the left sidebar.

14.4. Authorship of comments

Noteshare does not permit unsigned comments. Comments are dated and signed with the screen name of the commenter.

14.4.1. Permission to make comments

The author of a document can place it in a group and make it "commentable". If you are a member of this group, you can comment on it.

15. Extras

15.1. Attributes

Attributes can be used to insert commonly used bits of text in your document. A document in which a (long) company name appears frequently is a good candidate for this. Another is a legal document such as a will, which contains much boilerplate text and a few names that must be changed from document to document.

Define an attribute like this:

   :company: Humpty, Dumpty & Crutchfeld, LLC

Use the attribute like this:

   {company} affirms that its products are
   product are of the highest quality.

to get this rendered text:

Humpty, Dumpty & Crutchfeld, LLC affirms that its products are product are of the highest quality.

15.1.1. Attributes for a Notebook

Attributes can be define so that are in force throughout a notebook, rather than just in one section. To to this, go the control panel in the main edit page and select NA —  Notebook Attributes and imitate this example:

 {ymc} Yolac Muur & Sons, LLC.

Then you can say this anywhere in your document

The lowest prices from {yms}!

to get this:

The lowest prices from Yolac Muur & Sons, LLC!

15.2. Running apps in Noteshare

This example demonstrates the fact that one can run Javascript apps inside Noteshare. The method is simple. In the Noteshare Editor, paste the app code as in the template below:


You may need to refresh your broswer to run the app. For now you must request permission to run apps: jxxcarlson at gmail.

16. Test of embed feature

In writing up lecture notes it frequently happens that you need to spend considerable time writing up some standard topic that is quite well-known and likely treated elsewhere. Suppose that you, or someone else already wrote up a perfectly good treatment of this topic. Wouldn’t it be nice if you could just say embed::616223[] to embed document 616223 and then go on about your writing?

Well, that is now possible. Imagine that you are a math professor, and you need for your students to review basic manifold theory. Someone, some time ago, wrote this up in the document with id 1080. So we just reference it like we did document 616223 above. And voilà! Look below and behold!! (Scroll please — look for Manifolds).

16.1. Notes on the embed feature

At the moment, every document (note, or lessson) in Noteshare is referenced by an integer id. This may or may not be the way to go for a long future for this idea. What I envision is a site — or a network of sites, which is what noteshare appears to be to the user — within which anyone can embed a document when, where, and how he pleases as long as the author of the document has given permission for embedding. This is the DRY principle applied to a community of authors (where the community extends in space and time — author A may use the text of author B 30 years after author B has passed on).

There is a lot to be thought out, but I think that this could be a valuable feature. Note also that there is a kind of live update bonus: If the author of "Manifolds" below updates his version, the "Embedder" can re-render his document to get the update. How the author notifies the embedder needs to be though out also.

Here is the basic code that implements the feature (it has evolved a bit since first written):

def TextTransformer.execute_embeds(text)

    embedRX = /embed::(.*?)\[(.*?)\]/
    scan = text.scan embedRX
    for match in scan do
      oldText = "embed::#{match[0]}[#{match[1]}]"
      lesson = Lesson.where(id: match[0])[0]
      if lesson
        puts "EXX: I will embed lesson #{}"
        newText = lesson.original_content
        text = text.gsub(oldText, newText)

    return text

Note much to it, though this is a first and fast implementation.

The embedded section below is just a start on a rough draft. It is used here as a proof-of-concept only.


17. Features

During the one-year startup phase there is no annual membership fee for Noteshare, nor any distinction between standard and premium accounts. The annaual fee for the standard account will be in the neighborhood of $24. Pricing for the premium account has not been set, but it will not be high.

If your account becomes inactive, the content you create on Noteshare remains there. Just reactivate to start writing again.

17.1. Standard account

  1. Upload photos

  2. Search for individual notes, not just notebooks — by title, caption, tags

  3. Groups — participate in groups to share documents. Documents can be read-only or editable. Standard accounts will come with one ready-made group.

  4. Add sections to a document, move them around.

17.2. Premium account

  1. Upload audio and video as well as photos

  2. Create and manage groups. This way several people can collaborate on a writing project.

  3. Full text searches

  4. Use the embed feature — incorporate other Noteshare documents in yours by adding a short code, e.g., embed::61222 to embed the document with id number 61222.

17.3. In the pipeline

  1. Download all the documents, images, and other media that you create or upload

  2. Export documents to PDF and epub (electronic book)

  3. Export document to LaTeX (for math, physics, etc.)

  4. Cross-list documents with another Noteshare site. Imagine that you have written a great set of chemistry notes. It is available on your site, You submit it to It is accepted by the reviewer and listed at

This PDF file was created using Asciidoctor-pdf.

18. Series


- response -

19. Communication with Node.js server

Screen name:



- response -

20. Technical appendix

20.1. Problem sets, etc.

Noteshare can display lists of questions and answers, as illustrated in the fake quiz below. The answers (and the hints) are hidden until the user clicks on them. Clicking an item a second time hides it once again. Below is an abbreviated version of how we made first click-to-reveal element in the first question of the fake quiz:

.Problem {counter:problem}
What is the Pythagorean theorem?

It is the relation between the legs of a right
triangle and its hypotenuse:
pass:[\(a^2 + b^2  = c^2\)].

Click-to-reveal elements of a Noteshare document signal their presence via their blue title. To see how this document was written, choose Source from the View menu and compare what you see below with the source text.

You need to be signed in to have the View menu available and use View Source.
You can use the usual LaTeX dollar signs for the mathematics — use View Source to check this out. What you see above, with +( ... )+ also works.

20.2. Quiz #1

Problem 1

What is the Pythagorean theorem?

It has to do with triangles.
It is the relation between the legs of a right triangle and its hypotenuse: \(a^2 + b^2 = c^2\).
Problem 2

What is the Hodge conjecture?*

It has to do with algebraic cycles.
It is the statement that every ratoinal \((p,p)\) class is is the class of a rational algebraic cycle.

20.3. Quiz #2

Here is another style for writing quizzes, problem sets, etc.

  1. What is the \(y\)-intercept of the line defined by the equation \(2x + 5y = 10\)?

    Set \(x = 0\) and solve for \(y\).
    \(y = 2\).
  2. What is the slope of the line defined by the equation \(2x + 5y = 10\)?

    Solve for \(y\) in terms of \(x\), then look at the coefficient of …​
    $m = -2/5

In this style, we used an ordered list, and we use list continuations — the + symbol, to make sure that everything we wanted was grouped with the first item, then the second, and so on.

20.4. Technical note

This note describes how click-to-reveal elements are implemented using

20.4.1. CSS

Add this to your style file: {
  .title { color: blue; }
  .content {
    .paragraph {
      font-style: oblique;

20.4.2. Javascript

Add this to your javascripts:


  $('').click ->
It is the relation between the legs of a right triangle and its hypotenuse: \(a^2 + b^2 = c^2\).
Problem 3

What is the Hodge conjecture?*

It has to do with algebraic cycles.
It is the statement that every ratoinal \((p,p)\) class is is the class of a rational algebraic cycle.

21. Linking the main page and the aside

21.1. The Quadratic Equation

Let \(ax^2 + bx + c = 0\) be a quadratic equation. Its roots are given by the formula \[ x = \frac{ -b \pm \sqrt{b^2 - 4ac} }{2a} \]

21.2. The Cubic equation

The general cubic equation has the form \(ax^3 + bx^2 + cx + d = 0\). There is a formula for its roots, but that formula is not so widely known. The formula requires the use of complex numbers, even if the coefficients .

22. Asciidoc markup

Asciidoc markup is a system for formatting text, adding media, making hyperlinks and cross references, etc. Here is an example.

This text is bold this text is italic.

Here is what we wrote to achieve this:

This text is *bold* this text is _italic_.

Below we say more about markup. See for much more complete information.

22.1. Why Markup?

Markup goes against the prevailing ideology of WYSIWIG editing. But for authors who need to write a lot of structured text, markup has many advantages. First and foremost, you can write quickly and keep focused on what you want to express instead of breaking the flow by swtiching back and forth between keyboard, mouse, and menu. Using markup requires a small (surprisingly small) up-front investment in learning a new tool, but that investment will repay itself many times over as you write. See the section More Asciidoc Examples below to get started.

Second, markup can render text into many other formats: html (the web pages you see here), docbook, pdf, etc.

22.2. PDF

For some kinds of content, PDF is the way to go. In the New Course | Lesson | PDF menu, select PDF to create a new PDF file and attach it to a lesson.

To make a link to another VSchool lesson, all you need is its ID number. Here is a link: scientific method. It was created this way:

LITERAL::<<_before_the_beheadings, Scientific method>>

Look for the lesson ID in the upper right of the gray banner.

22.4. More Asciidoc Examples


Twas brillig, and the slithy toves
  Did gyre and gimble in the wabe:
All mimsy were the borogoves,
  And the mome raths outgrabe

To achieve this, we wrote

Twas brillig, and the slithy toves
  Did gyre and gimble in the wabe:
All mimsy were the borogoves,
  And the mome raths outgrabe

There are many markup codes, but you will need just a few for most of what you do.


== Level 1 heading
=== Level 2 heading
==== Level 3 heading
===== Level 4 heading


  1. Apples

  2. Pears

  3. Bananas

. Apples
. Pears
. Bananas
  • Apples

  • Pears

  • Bananas

- Apples
- Pears
- Bananas


http:://[New York Times]

http:://[New York Times]

See for more information.

22.5. Defining macros

To define TeX macros in the text of a document, imitate this example:

\newcommand{\sett}[2]{ \{\,#1\, \mid\, #2\, \} }

Then you say

$ \QQ = \sett{a/b}{a, b \in \ZZ, \ b \ne 0} $

to get

\( \QQ = \sett{a/b}{a, b \in \ZZ, \ b \ne 0} \).

22.5.1. Notebook Macros


It is usually more convenient to define macros in such a way that they can be used for an entire noteobook. To do this, put tex like that below in the Notebook Attributes field. To so this, go to the main edit window and press the button NA.

\newcommand{\sett}[2]{ \{\,#1\, \mid\, #2\, \} }

1. We are working on a prototype asciidoctor-to-latex converter. At the present moment it is adequate to convert this file into LaTeX. Stay tuned!