md-notes v1.0.2

#md-notes

Easy way to take quick markdown notes, and produce a single, easy-to-share, and pretty html file from them. You don't need to be connected to the internet to use it. It has many configuration options as well to be flexible for your needs.

##Install You have to install node or iojs if you have not already and then npm install -g md-notes.

##Take Notes To start taking notes in a directory, simply run md-notes [options]

[options]:
	--port=<port>: port to host the live-reload server on (default 7000)
	--throttle=<ms>: number of ms to throttle the reloads. (default 1000ms)
	--title=<string>: title of the output html file (defaults to name of current directory)
	--src=<files/dirs/globs>: comma separated list of places to look for markdown files. (defaults to ./notes).
	--outfile=<file>: where to place the output html file (defaults to ./notes.html)
	--update: only update the output file given the --title, --src and --outfile arguments, do not run the server
	--hideStartNums: use the numbers at the beginning of file/dir names for sorting only, hide in the output file

If you run just md-notes without any args, you will start a server that watches the changes you make to markdown files in the notes/ directory and updates notes.html file. It also opens a browser to localhost:7000 so you can view your changes real-time

NOTE: You will probably have anywhere from 1-3 windows open at a time while writing notes

• 1 window if you run md-notes --update infrequently and just want to write your markdown notes without the live reloading, OR if you have the server running as a background process in your terminal but do not have a browser open
• 2 windows if you want to run the live reloading but don't want to open a browser to view the changes, OR if you have the server running as a background process in your terminal and have a browser open

• 3 windows open if you want live-reloading and want to view the changes as you type/save your markdown files

###Demo: This is what the generated html for this project looks like if you run md-notes --update --src="**/README.md", which will generate an html document from all the README files in the md-notes directory, including the node_modules folder:

This is one option for a workflow: Run server in one terminal, edit files with Vim in another terminal, and watch changes in a browser. Notice how the scroll, nav-menu state, and selected nav-item are all saved when the page is refreshed while writing your markdown files. this makes developing realtime much easier. The refreshing picks up file creation, deletion and changing.

The generated html file contains a navigation menu on the left side, and the concatenated markdown files in the content panel. The content panel is filterable, so if you click on a directory in the nav-menu, the content panel will only show the markdown files underneath that directory. If you click on a file, the content panel will only show that file.

###Examples: This will run a server and continually update the notes.html file and also in the browser.

md-notes --src=notes --outfile=notes.html

This will run the server on port 8080 and update at most 1 time every 300ms

md-notes --port=8080 --throttle=300 --src=notes --outfile=notes.html

This will simply update your html file with the markdown files and not run a server or open a browser

md-notes --src=notes --outfile=notes.html --update

###Much simpler examples If you just want to use defaults (recommended) for the html file and the notes directory, the previous examples become:

md-notes
md-notes --port=8080 --throttle=300
md-notes --update

###Valid file extensions md-notes will only pick up files with any of the following extensions: mark|markdown|md|mdown

###Flexible in what files you include in the output html file This supports selecting individual files, directories, globbing patterns, or a combination of the three

md-notes --src="notes/ch1/**"
md-notes --src="notes/ch2/intro.md"
md-notes --src="notes/ch2/section2/"
md-notes --src="notes/ch1/**,notes/ch2/intro.md,notes/ch2/section2/"

###Smart sorting of your files The generated html file will sort by the numbers found in the file or directory name. If there are no numbers, the path will come before paths with numbers. If multiple paths have no numbers, or have the same numbers, it will sort only using alpha characters.

An example of how two files are compared:

file A, "notes/ch1/section 1-1-2.2.md", we ignore"notes/ch1/" and path resolves to numbers [1,1,2,2]
file B, "notes/ch1/section 1.1.3.md", we ignore"notes/ch1/" and path resolves to numbers [1,1,3]
the 1's cancel out so we have file A [2,2] and file B [3]
since 2 < 3 file A would come before file B 

Another example:

file A, "notes/ch1/section 1.md", we ignore"notes/ch1/" and path resolves to [1]
file B, "notes/ch1/section 1 extra notes.md", we ignore"notes/ch1/" and path resolves to [1]
the 1's cancel out so we have file A [] and file B []
since there are no numbers left we convert file A to [section .md] and file B to [section  extra notes.md]
we sort alphabetically without numbers included, and file A comes before file B

This is how the following files would sort:

notes/ch1/intro.md
notes/ch1/second intro.md
notes/ch1/section 1.md
notes/ch1/section 1 extra notes.md
notes/ch1/section 1.1.md
notes/ch1/section 1-1-2.md
notes/ch1/section 1-1-2.2.md
notes/ch1/section 1.1.3.md
notes/ch1/section 1.4md
notes/ch1/sec 4 recap.md
notes/ch1/section 8.md 
notes/ch1/section 13.md 
notes/ch1/14 section overview.md
notes/ch1/15.md
notes/ch1/section 20.md
notes/3 chapter/section 1.md
notes/3 chapter notes/section 1.md
notes/ch3/section 1.md

###Hiding Numbers if you dont want to show them The above section described how sorting works. Sorting by numbers is handy, but you might want to specify your own order that is not aphabetical. in this case, you want to use the --hideStartNums option. This will sort by the above algorithm, and then remove any numbers at the BEGINNING of the file/directory name.

So these files:

book/0 Introduction.md
book/1 Acknowledgements.md
book/2 Chapter 1: Writers Block.md

When run with command md-notes --hideStartNums --src=book would resolve as

book
	Introduction
	Acknowledgements
	Chapter 1: Writers Block
	

in the generated html file

###You can change the title of your html output file By default, it uses the name of the current directory.

mkdir physics_100
cd physics_100
md-notes

The above will produce an html file that says 'phsyics_100' at the top of it.

mkdir physics_100
cd physics_100
md-notes --title="Physics 100 Lectures"

The above will produce an html file that says 'Physics 100 Lectures' at the top of it.

###Using --title and --src to make html views for certain classes, weeks, etc.. Using --title and --src together are useful if you have lots of notes files from different lectures or chapters, but only want to share a specific subset of them. e.g: Maybe a friend missed a week and needs notes.

md-notes --title="Lectures 3.1 - 3.3" --src="lectures/3.1.md,lectures/3.2.md,lectures/3.3.md" --outfile="lectures 3.1-3.3.html" --update

###Source Directory shows up the same way in the html file navigation The navigation tree in the html page will look the same as the directory structure you feed into the --src. So if you run md-notes --src=notes, and this is your directory structure:

notes	
	ch1
		s1.1 
		s1.2
	ch2 
		s2.1
		s2.2
			s2.2.1
			s2.2.2
			s2.2.3
		s2.3
		

then your navigation menu sidebar when you open the html file will look like this:

ch1
	s1.1 
	s1.2
ch2 
	s2.1
	s2.2
		s2.2.1
		s2.2.2
		s2.2.3
	s2.3

###No Internet Required The notes.html file produced by the server uses pure javascript, css and html in a single human readable file. That means you can open the html file in any browser or text editor and not expect a 100000 line mess of bootstrap, angular, jquery or something else. It also doesn't pull files from a CDN (hence the no internet part).

###Limitations and known issues If you start messing with files outside your current working directory, the behaviour is undefined, as I have not tested this.

If you are writing to a file at the filesystem root, such as C:\a-file.md or /a-file.md, it wont work. Sorry.

###People Samuel Steffl @ssteffl is the author

###Bugs and Enhancements please report bugs or feature requests to the github repo