Apage

Apage generates a single HTML page from multiple markdown sources

• Homepage
• Documentation
• Test
• Fork Apage on GitHub

Documentation

• Home
• Installing Apage
• Testing Apage
• Installing Build Tools
• The Build Process
• Handy Scripts

Installing Apage

Old fashioned browser install, providing window.Apage:

<script src="http://apage.richplastow.com/build/apage.js"></script>
  <script>console.log( new window.Apage().I ); // -> 'Apage'</script>
  

Install as a CommonJS Module, eg for Node:

var Apage = require('apage');
  console.log( new Apage().I ); // -> 'Apage'
  

Install using RequireJS inline-style, providing Apage as an argument:

<script src="lib/require.js"></script>
  <script>
    require(['path/to/apage'], function(Apage) {
      console.log( new Apage().I ); // -> 'Apage'
    })
  </script>
  

@todo more installation examples, including $ npm install -g apage, etc.

Testing Apage

Test with npm run-scripts on the command line:

npm test
  

Test on the client:
Open test/run-test.html in a web browser

Installing Build Tools

The following modules are listed in the "devDependencies" field of ‘package.json’, so running npm install will install them in the local ‘node_modules’ directory. However, you may find it useful to install them globally on your machine, in which case the -g flag is your friend:

Install coffee 1.9.2 on the command line:

npm install -g coffee-script
  

Install nodemon 1.3.7:

npm install -g nodemon
  

The Build Process

Build Apage on the command line

npm run build
  

@todo discussion of the limitations of file-watching.

Handy Scripts

hi

Opens up four useful project windows, saving you a few precious seconds at the start of a development session. You will need Sublime Text installed, and a symlink to its subl binary added to your PATH.
@todo cross-platform, eg xdg-open (*nix) and start (win)

npm run hi
  

Which runs:

open .; open index.html; open test/run-test.html; subl .
  

Which means:

1. Open the present working directory. On OS X, this opens a Finder window
2. Open the project’s local homepage using the default browser
3. Open the client-side test page using the default browser
4. Open the project in Sublime Text

v:list

Shows a list of files which contain the version string from ‘package.json’. Each filename is suffixed by a colon, followed by the line-number where the version string appears, eg README.md:1 package.json:4.

npm run v:list
  

Which runs:

grep -ron $npm_package_version {bin,src,*.json} | awk 1 ORS=' ' | sed "s@:$npm_package_version@@g"
  

Or verbosely:

grep --recursive --only-matching --line-number $npm_package_version \\
  {bin,src,*.json} \\
  | \\
  awk 1 ORS=' ' \\
  | \\
  sed "s@:$npm_package_version@@g"
  

Which means:

1. Use grep to get a newline-delimited list of files which contain the version string from ‘package.json’
   • --recursive search in subdirectories
   • --only-matching don’t show leading/trailing context in the results
   • --line-number included after a colon, eg bower.json:3
2. Search in bin/, src/, package.json, bower.json, etc
3. Pipe the list to awk
4. Convert all newlines to spaces
5. Pipe the list to sed
6. Delete the trailing colon and version from each filename, eg :1.2.3-4

If you want to find for a particular string in the repo content, use:

grep -r 'the string' *
  

v:open

Opens a list of files which contain the version string from ‘package.json’ in Sublime Text. You will need Sublime Text installed, and a symlink to its subl binary added to your PATH.

npm run v:open
  

Which runs:

subl $(npm run v:list --loglevel silent)
  

Note --loglevel silent, which prevents subl from being sent the results-log which npm run usually outputs.