Published by

\( \def\ZZ{\mathbb{Z}} \def\EEE{\mathcal{E}} \def\ffp{\mathfrak{p}} \def\bold#1{\bf #1} \newcommand{\set}[1]{ \{\,#1\, \} } \def\dim{\mathop{dim}} \)

What Is Noteshare?

44880 guten press lg

Noteshare is a tool for creating and sharing documents online. We’ll call these documents notebooks. A notebook can be anything: notes for a project, a diary, a collection of poetry. It can be a set of lecture notes or homework problems for a class you are teaching, or an online textbook. It can be a cookbook, a machine shop manual …​ you name it!

Noteshare Quick Start will get you started writing interesting documents with just an hour’s practice. To get an idea of what is possible, take the tour. To see how a noteshare document is made, look at Sample documents A, B and C in the next three sections.

To learn how to create a new notebook, write, edit, and save text, go to creating a document. To learn how to structure a document with sections and subsections, re-order these, etc. see structuring and formatting text. You will need this as your notebooks grow larger. The rest of this guide addresses the needs of specialized authors and their audiences. Read those that pertain to you.

Images and other media


In addition to text, Noteshare documents can contain images, audio, and video, links to web sites, and links to other noteshare documents. You can write mathematical formulas, list computer code, and attach pdf files — scans of handwritten notes, diagrams, drawings, etc. Below, for example, is how you insert an image in a notebook once you upload it to Noteshare.

IMAGE::460[float=right, width=125]

The number 460 is the ID of the image. You will learn about ID’s later — they are a kind of Social Security number for media, documents, you name it. If you are curious about ID’s, take a look at the media database now. Anything you see there can be incorporated into what you write. And of course you can upload your own images. To find an image, use the search box at the top of the Media tab. Try a search on the word bird.

Question and answer format

Of value to anyone who teaches is the question-answer format of the example below — good for problem sets, course notes with exercise, etc. If you click on the text "Answer" the answer will be revealed. If you click a second time, it will be hidden. Questions are automatically numbered. (You may need to refresh your browser for this feature.)

Question 1.
Who is buried in Grant’s tomb?
President Ulysses S. Grant
Question 2.
What is the chemical formula for sucrose — cane sugar?
\[ \ce{C12H22O11 } \]
Question 3.
What is value of the integral \(\int_0^1 x^n dx\)?
\[ \int_0^1 x^n dx = \frac{1}{n+1} \]

Noteshare has a wealth of features, but this is enough for now.


One of the best ways of learning Noteshare is to look at examples. By comparing the source text — what you write — with the rendered text — what your readers see — you will quickly learn what you need to know. To this end, there is a set of samples documents at, e.g.,

Below is one very short example, with the source displayed in the sidebar.

Norbert Yocum, Organized Man

Mr. Norbert Yocum is a punctilious maker of lists:

Early Morning List
  1. Get up

  2. Shave & Shower

  3. Make breakfat

    1. Orange juice

    2. Cereal

    3. Coffee

  4. Read the New York Times for exactly 11 minutes

He is fond of algebra and loves the formulas \(a^2 + b^2 = c^2\) and \[ \int_0^1 x^n dx = \frac{1}{n+1} \] In his spare time he likes to experiment with electronics. He keeps a journal which records each experiment:

relaxation oscillaotor
Figure 1. One transistor relaxation oscillator

Each night before going to bed, he reads a bit of poetry, usually of modest literary quality:

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!"


Creating a document

Screenshot 2015 09 21 13.14.00
Figure 2. Editor tool panel

In this lesson, you will learn how to create and edit new Noteshare document. It will be much like writing an email — no special formatting. Just type away. In the next lesson, you will learn how to structuring and formatting text your text --- add sections, create numbered lists, write bold and italic text, etc.

Throughout you will use the tools in the editor tool panel pictured above. For now you will need just two of the tools in the panel. For a description of what the buttons do, see buttons of the Help Notebook.

Note that if you place the cursor over a tool and wait a second or two, a short description of the tool will appear.


Creating a document

  1. Open Noteshare in a second window or browser tab so that you can follow these directions and experiment at the same time. When you have the new window up, press the home button home_black. In the middle column where your notebooks are listed, select the new document tool new_document.

  2. A form to fill out will appear. You can put "Test" for Area and "First Notebook" for Title, or you can put something of your own choosing. The Tags field is optional.[1] Press Create.

  3. You will see a page with a smallish First Notebook followed by a large TITLE.. To the left of First Notebook, you see the edit too edit. Press it.

  4. You are now in the editor. You see two "window panes." On the left is your source text. On the right is the rendered text. For the moment there is not too much difference between source and rendered text. We will get to that later. You are going to change the source text. This is what you see:

     == TITLE
    Your text here

Replace TITLE by your own title, add a blank line, and then your own text. Type as much as you want, and don’t worry about formatting. Press return whenever you need or want to. To see the changes you have made and to save your work, press the update button at the bottom of the page. You can also press Ctrl-U. Look at the text in the right part of the page — the rendered text. It has changed. Continue writing. Press update or Ctrl-U from time to time, To return to where you began, press exit or Ctrl-X. (This button is like "cancel". It does not save your work.)

Don’t change the two equal signs (==). They tell Noteshare that TITLE (or whatever you replace it by) is a section heading. A section heading always has the form two equal signs starting at the left margin followed by a space followed by the title.


  1. To make a new paragraph, insert a blank line, then continue writing.

  2. You may notice sometimes that your text looks strange, like

    here is some of my text
       why does it
          look so weird?

    What happened?? Well, by design or by accident, you began your paragraph with a space. This is the signal that Asciidoc uses for verbatim text: that is, text with no formatting, and all spacing respected. This can be useful, but it is not usually what you want to do.

    Standard procedure is to start writing at the left margin.

  3. In the source text, don’t worry about line endings. Just type away, and press return on your keyboard whenever you want.

Creating a new section

Before you leave this lesson, let’s create a new section and add a little text to it.[2] When you pressed exit, you went to a page that displayed what you had typed. This was in the middle column. On the left is a table of contents with just one item. Above the table of contents you see some buttons. In the editor tool panel find the new section tool new and click it to create a new section of your notebook. You can also press Ctrl-N. Then create some text using what you have learned in this lesson.

Now you can relax! Good job!! You have created a notebook and written some text in the first section of the notebook. Then you created a new section. It’s time for a break.

Back from your break? The last part of this lesson is easy — just explore the View menu.

View menu

Take a look at the View menu. It has these items:


three-column view with table of contents


a view with out the editing tools


source text on left, rendered text on right


a printable view of the current section

Whole doc

a printable view of the whole document


convert the current section to LaTeX (experimental)

Experiment with these menu items to see what they do. The Source item is especially useful when you are learning Noteshare. It displays the source and rendered text side by side but doesn’t allow you to change anything. Take a look at this section now using Source — see if you can figure out how it was made!

Structuring and formatting text

In the first lesson, you wrote unformatted text whose only structure was that of the paragraph. In this lesson, you will learn to structure and format text by putting little markup codes in it. For example, to italicize text, you write _italicize text_, Here the markup code is the underscore symbol: _. For another example, consider bold text, which you get by writing *bold text*. Here the markup code is the asterisk: *.

The codes _ and * are part of the Asciidoc markup language. The engine that powers Noteshare is Asciidoctor, a very fast Asciidoc processor that has other important features. It can, for example, export documents to PDF files, EPUB3 (electronic book) files, as well as LaTeX files. LaTeX file export is experimental, but is in reasonably good working order.

Our goal in this lesson is to learn enough markup to write documents with section headings, numbered lists, images, and links to web sites.

Rendering text

When you presed the update button or type CTRL-U as in the previous lesson, you told Noteshare to process the marked-up source text to produce the rendered text: source text ⇒ rendered text. When the source text is marked up, the rendering process is more interesting:

Screenshot 2015 01 08 16.23.27
Screenshot 2015 01 08 16.32.54

Once you get used to marking up your text, you will find that you can write much faster and stay better focused on your writing than when you have to pause, select text, go the menu, etc.

A Realistic Example

Imagine for a moment that you are a teacher and that you use Noteshare every day to write your lesson plans. One of them, titled Tuesday’s Lesson Plan, is in the sidebar on the right. Take a look through Tuesday’s lesson plan now.

Let’s compare the source text for the Lesson Plan, listed below with the rendered text. The goal is to get a general idea of how the markup affects the rendered text, not to understand it in detail. After you have done the comparison, the section markup, will give a detailed explanation.

As you compare the two versions, pay attention to the following elements:

  • bold and italic text

  • section headings

  • numbered lists

  • images

  • links to web pages

==== Tuesday's Lesson Plan

Today we will focus on _matter_. This is stuff
of  which planets, houses, people, butterflies,
bacteria,  and a cup of coffee are made. Matter
itself is made up of tiny, tiny particles called
_atoms_, and these in turn are made of

. Protons
. Neutrons
. Electrons

==== Homework

. Read the[chem4kids article]
about atoms, then answer the questions below.

. How many protons does a hydrogen
atom have? How many electrons?

. How many protons, neutrons,
and electrons does a carbon atom

. What determines the chemical
 properties of an atom?

. What are the most massive
("heaviest") parts of an atom?

!!IMAGE::185[width=200, align=center]

*Your assignment is due this Friday.*

*Extra credit.* The image above
is the first ever made of a single
hydrogen atom.  Read about it[here]
and write an essay on the theme
 "Seeing things that are very small."

<<_atomic_theory, Further reading>>


Let’s review what you have discovered by comparing the marked-up source text for the lesson plan with the nicely formatted rendered text.

  1. To write bold and italic text. For bold text, put an asterisk before and after: *bold text*. For italic text, put an underscore before and after: _italic text_.

  2. To make a section title, write == section title or === subsection title, or ==== subsubsection title, etc. Be sure to start right at the left margin.

  3. For each item in an automatically numbered lists, write a period, a space, and then the item. (For bulleted lists, write an asterisk, a space, then the item).

  4. To add images, you first upload them to the Noteshare media library. We will learn how to do this in the next lesson. Every image has a numerical ID. The ID number for the atom image is 185, so we wrote this:

    !!IMAGE::185[width=200, align=center]

    to include the image in our document.

  5. To link to a web page like, just write the URL (web address) with the link text in brackets.[New York Times]

    The text with the brackets is optional, but is a good way make the link shorter and fit your needs. Look to the right to compare the very long link in the source of the Extra Credit section with the rendered version, where all you see is an underlined "here".

  6. You can also link to sections of other Noteshare documents. Like images, each section has a numerical ID. We linked to the section with ID 540 like this !!XLINK::540[Further reading].

That’s it! You have learned about bold and italic text, section headings, lists, images, and links. With these six elements of the Asciidoc markup language, you can write 90% of what you will want to write on Noteshare.

Using what you have learned

Screenshot 2015 09 21 13.14.00
Figure 3. Editor tool panel

You have looked over the lesson plan and learned some basics of the Asciidoc markup language. It is time to put these new tools into practice — go to the tab or window in your browser where you have Noteshare open. Near the top of the left-most column, you should see the Editor Tool Panel, as in the figure. Click on the new tool to create a new section.. Create some text using what you have learned in this lesson.

  • If you have "lost" your notebook, press Home. It will be listed in the middle column under my notebooks. Or you can type the name of the notebook in the search box in the top left of the menu bar.

  • If you don’t see the three buttons, press the buttons Write, then Read.


  1. You noticed that there was a link at the beginning of this lesson to the section titled Asciidoc used in the lesson plan. Here is how made that link:

    Screen Shot 2014 12 20 at 10.29.30 PM
  2. You can make nested lists like this:

    . Grocery store
    .. Eggs
    .. Bacon
    .. Orange Juice
    . Hardware store
    .. Nails
    .. Caulking compound

    For an un-numbered list use asterisks instead of periods:

    *Grocery store
    ** Eggs
    ** Bacon
    ** Orange Juice
    * Hardware store
    ** Nails
    ** Caulking compound

Keyboard short cuts

ctrl = Control Key
alt = Alt or Option Key

Main page

ctrl-B — Browse
ctrl-R — Read
ctrl-W — Write
ctrl-M — Media

ctrl-P — Print — show printable version of page

ctrl-N — New section
ctrl-E — Edit current section
ctrl-A — Edit aside for current section


ctrl-U — Update: save source text and refresh rendered text
ctrl-X — Exit editor without saving


Clepsydra Diagram Fancy

You can put many types of media — images, audio, and video — in a VS document. To do so, you will use the Noteshare media library, In it, every file is identified by a numerical ID. The image on the right, for example has ID 120: Below, we describe how to

  1. Search the Media Library

  2. Place files already in the Media Library into your document

  3. Upload files to the Media Library

Searching the Library

Searching by ID

The media library can be searched by by keyword or ID. Press Media in the far right of the menu bar. Once you the Media screen comes up, you will see two search boxes in the left-hand part of the menu bar. Type the number 120 in the left-hand box, then press RETURN. What image do you see?

Searching by Keyword

Let’s use this search feature to find an image of a bird. In the second of these, put the word "Bird" and press RETURN. What images do you see? Scroll down until you see the image with ID 458. What kind of bird is it?

Random Search

Notice the word Random in the menu bar of the Media tab. Each time it is pressed, a set of random images is displayed.

Placing Images

You saw then image below when you searched for "Bird" --- it was the image with ID 458. We inserted it in this document with the code


The space between the brackets in IMAGE:458[] is for options that control the size and placement of the image. Here are some examples:

  • IMAGE:458[width=200]

  • IMAGE:458[width=200, float=left]

  • IMAGE:458[width=200, align=center]

Here, for example, is the 200-pixel wide center-aligned image:


You can also put a caption on the photo, as in the example below.

Figure 4. Cardinal

In the case of the captioned image, we have "floated" the image on the left, meaning that the text written below it will wrap around the image. Notice, by the way, that the caption is automatically numbered. There is, of course, a way to turn automatic numbering off. For this and much more information about images, see the Asciidoctor User Manual.

You can center an image with a centered caption. Look below the image for the code for this.
king parrot sep06
Figure 5. King parrot
.King parrot

Other Media


Reference video files using the VIDEO tag. Thus, use


to place the video below.


The same technique applies to audio files:


to place this:


External Media


Add a Youtube video using its embed code, e.g. EsTgr-n53Ow?. Then you can write video::EsTgr-n53Ow?[youtube,width=575,height=350] to display the video below.


Inserting ontent from vimeo is done in much the same way. Thus, write VIDEO::111593305[vimeo] to display the video below.

Uploading Media

To add a media file to the Noteshare library, proceed as follows:

  1. Select the Media menu item (upper right).

  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.

Once your file is uploaded and you have the ID number, you can insert in your document, following the directions of the previous section. I you were already writing something and switched over to Media, press "Write to switch back.

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.


Suppose you want to construct a table, e.g..,

Table 1. Groceries


one dozen


twelve pounds


three quarts

Use the source code below as a model. For more on tables — formatting, etc., — see the tables or the complete reference, Asciidoctor User Guide

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

Click blocks

Look at the next paragraph. You see the words "Comment" in blue. Click on the word "Comment". What happened?

This is a click block. Click the header again to hide me.

Click blocks a good way of making problem sets, training documents, etc. We used them in this way in the section, what is noteshare.

How to make a click block

Imitate this example to make click block:

This is a click block.  Click the header
again to hide me.

Environment blocks

An environment block is much like a click block, except that the header is red and the body is always visible. Environment blocks are automatically numbered, unless you tell them to behave otherwise. Here is a typical environment block

Fact 1.
Hot air rises.¨

And here is how it is written:

Hot air rises.¨

The header of a basic environment block has the form [env.TYPE], where TYPE can be any string e.g., fact, question, comment, theorem, equation, joke. The numbering of environment blocks depends on the TYPE. Thus jokes are numbered separately from facts and theorems.


Use environment blocks to automatically number elements, as in the examples below. Choose Source from the View menu to see how these were done.

Fact 2.
The population of the US was 316.1 million in 2013
Fact 3.
The area of the US is 9.857 million km2.
Question 4.
What is the population density of the US?
Density is a ratio. In this case, the ratio of what to what?
Work in millions of units: \[ 316.1/9.857 = 32.1\ persons/km^2 \]
Question 5.
What is the population density of France?
Question 6.
If the US had the same population density as France, what would its population be?


Environment blocks can be labeled and cross-referenced. For example, consider Fact Fact 2. This is a cross -reference to the fact bout the US population mentioned above. It was written like this

The population of the US was 316.1 million in 2013

The string population-us after the symbol # is the label for the env block. We used this label in constructing the cross-reference:

Screenshot 2015 01 10 12.09.52

The general form of a cross-reference is

Screenshot 2015 01 10 12.12.11


You can freely use (and invent) blocks like [env.theorem], [env.definition], etc. These will be translated into the corresponding LaTeX environments if you convert a VS document into LaTeX (see XX). You can label and cross-references these blocks as described in the previous section.

Some blocks receive special treatment. One of these is the equation block:

a^2 + b^2 = c^2

It is rendered like this:

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

The VS equation block is very much like the LaTeX equation environment: equations are numbered by default and one can be cross-referenced. Thus, we may refer to the famous formula equation 1 using the method of the previous section —  enclose the label eq-pythagoras in double pointy brackets. Notice that the display delimiters \[ …​ \] are not needed in the equation environment.

Computer code

sum = 0
k = 0
while k < 100:
  k  = k + 1
  sum = sum + 1.0/k


Write formulas, equations, etc. using LaTeX:, e.g., $`a^2 + b^2 = c^2`$ for the Pythagorean formula, $a^2 + b^2 = c^2, and

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

for the integral formula \[ \int_0^1 x^n dx = \frac{1}{n+1} \] Noteshare usually recognizes the fact that you are writing mathematical text, but if not, put the code :latex: somewhere in your text.


In place of LaTeX environments, use Asciidoctor environments. For theorems, e.g.,

Theorem 1.
The square on the hypotenuse is the sum of the squares on the other two sides.

use this template:

The square on the hypotenuse is the
sum of the squares on the other two sides.

This construct is an example of a block. The body of the block is the text between the dashed lines. The body may contain both in-line and display mathematics:

Theorem 2.
The equation \[ z^n = 1 \] has \(n\) distinct complex solutions.

We wrote it this way:


The equation
  z^n = 1

has $n$ distinct complex solutions.

The string cyclotomic after the mark \# is a label used in cross-referencing. Thus w may later say: "Ahem, and I refer you to Theorem Theorem 2. The reference is written << cyclotomic >> , but with no wpace on either side of the word "cyclotomic."

You may use [env.equation], [env.definition], [env.joke], etc. — whaterver you like. Each kind of element is separately numbered,.

Some environment blocks receive special treatment. One of these is [env.equation]. For example, the source text

\sum_{n=1}^\infty \frac{1}{n} = \infty

renders as

\[ \sum_{n=1}^\infty \frac{1}{n} = \infty \]

Equations may be labeled and referred to as before.

Macro definitions

You can put macro definitions in you documents like this:

   \newcommand{\Set}[1]{ \Big\{\,#1\,  \Big\} }
\( \def\NN{\mathbb{N}} \newcommand{\Set}[1]{ \Big\{\,#1\, \Big\} } \)

Then the source text

  \NN = \Set{ \ldots, -2, -1, 0, 1, 2 \ldots }

is rendered as \[ \NN = \Set{ \ldots, -2, -1, 0, 1, 2 \ldots } \]

Macro definitions can also be put in the "Attributes" screen of a notebook, in which case they are available for use in all sections. Below is an image of the screen in question. You get to it by going into the document editor (select Edit or Write), then from the Edit menu, select Notebook ...

Screenshot 2015 02 27 07.44.10

The macros that you put in "Attributes" should follow this form:

\def\bold#1{\bf #1}

\newcommand{\set}[1]{ \{\,#1\,  \} }

Conversion: Noteshare to LaTeX

Use the downlod tool download to download a complete set of files for your notebook - text files, image files, etc. This set will contain .html, adoc, and .tex files that represent your compiled noteobook. The conversion from asciidoc to LaTeX is experimental.


Write in-line chemical formulas using the chem::[…​] macro. Thus, to say \(\ce{ CO2 }\) makes \(\ce{ H2O }\) fizzy!, we say

chem::[CO2] makes chem::[H2O] fizzy!

This macro and the next are wrappers for Martin Hensel’s mhchem ¬®package. What about displayed reactions, like the following?

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

For these we use the chem environment, e.g.,

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

More examples

\[\ce{NaHCO3 + CH3COOH → CO2 + H2O + Na+ + CH3COO-}\] (2)
NaHCO3 + CH3COOH -> CO2 + H2O + Na+ + CH3COO-

The little piece of code fizz after the symbol # is a label. It is used for cross references 2 — see bottom of this page.

\[\ce{Zn ←→ Zn^2+ + 2e-}\] (3)
.Electrochemcial reactions
Zn <--> Zn^2+ +  2e-
\[\ce{^{227}_{90}Th+}\] (4)
\[\ce{A\bond{-}B\bond{=}C\bond{#}D}\] (5)
\[\ce{SO4^2- + Ba^2+ → BaSO4 v}\] (6)
SO4^2- + Ba^2+ -> BaSO4 v

Cross references

Reaction (2) is one that you can demonstrate at home.

Reaction (<<fizz>>) is one that you can
demonstrate at home.

Document organization

Screenshot 2015 09 21 13.14.00
Figure 6. Editor tool panel

As your document grows, you will find that you want to re-order sections and subsections For this you will use the editor control panel (right). If you press the Table of Contents Tool, toc, you will get three-column screen with section numbers, e.g., 1, 2, 3.1, 3,2, etc. section titles, and blank boxes. The figure below titled Hodge theory, illustrates this.

Screenshot 2015 03 16 08.46.57

Suppose you want section 2.2 to be where section 2.1 is. Just type 2.1 in the box on the right of "2.1 Topology". Press return, and the change is made.

The same principle works on the setion level: type 1 in the box to the right lf "2 Elliptic curves" to promote the latter to frist position.

You can also promote subsections to sections and demote sections to subsections. Type 3 in the box to the right of 3.2 Projecive Space. The projective space will become the new section 3, with Basic Algabraic Geeometry pushed down to become section 4.



1. Tags help other people —  and maybe you also — to find your document
2. Later we will how to change order of sections