Posts Tagged ‘wiki’
Relative links in PNotes
May 31st, 2010 at 4:13 pm
In the last big change to my no-server wiki system—which I now call PNotes—I added the ability to categorize notes by subdirectory. This made PNotes more organized, but because I took some shortcuts in the programming I lost some of the portability of the system. In the last few days I’ve fixed the code to get portability back and uploaded the fixes to the PNotes GitHub repository.
One of my goals with PNotes was to create a wiki-like system that was self-contained within a folder—no reliance on a database system. I wanted to be able to move the PNotes folder anywhere—from place to place on my main computer, to my notebook, to someone else’s computer, to a CDROM or DVD, to my iPhone—and still have it work. When I added the ability to have notes in subdirectories, I decided to use a <base> tag in the <head> of each note to make it easier to generate the list of links in the sidebar.
The <base> tag made all the sidebar links absolute instead of relative, and this broke the portability I wanted. I could still move a PNotes folder anywhere on any of my computers because my computers have all the utility programs needed to regenerate the HTML files in their new location—all I had to do was reset the <base> and run make clean; make in the new directory. But I couldn’t zip up a copy of a PNotes folder and send it someone else, nor could I put it on my iPhone; the <base> would be wrong and screw up all the links.
Now, through a combination of Python and JavaScript, PNotes portability has been restored. You’ll need one line in the project.info file,
dirname = notes
to tell the system the name of the PNotes folder. I’ve always just used “notes,” but you can use any name as long as you set the dirname option accordingly. (I strongly suggest you stick to alphanumeric characters; the folder name is used in a regular expression, so special characters like parentheses and hyphens could mess things up)
Strictly speaking, the new PNotes isn’t perfectly portable. For example, the two “Edit” links in the sidebar won’t work unless the computer understands the txmt:// URL scheme for opening a file in TextMate (or BBEdit). And the contacts links won’t work unless it understands the addressbook:// scheme and has the same list of contacts with the same Address Book IDs. But all the links to notes should work on any computer.
The latest changes have made the GitHub README for PNotes a little out of date. I’ll be fixing it up in the next few days.
PNotes
February 11th, 2010 at 10:35 pm
Here are a few miscellaneous paragraphs about my no-server personal wiki system.
I’m tired of calling it “my no-server personal wiki system.” From now on it’ll be called PNotes, which will at least save me some typing. Its GitHub repository will remain the same.
PNotes is missing two things most wikis have: a history of edits and a search field. But it’s easy to overcome both of these limitations.
When I need to create a set of notes for a new project, I copy the PNotes notes folder—my local version of what’s in the GitHub repository—to the new project’s folder and delete the .git subdirectory inside it. I then issue a
git init
command from within notes. This starts up a new git history that will focus not on the programming, which probably won’t change at all, but on the content files. From this point on, I use git add and git commit whenever I think it’s warranted. I’ve thought about putting git commit into the PNotes makefile, forcing a commit whenever I modify or make new HTML pages, but so far I haven’t done so. I prefer the freedom of committing only when I can think up a good commit comment.
Searching hasn’t been as big a deal as I first thought it would be. Normally, I know exactly which note page will have the information I’m looking for, and finding it is simply a matter of scrolling or using the browser’s Find command on that page. For those few occasions when I couldn’t remember where a piece of information is, I just opened a Terminal window in notes and used grep to find what I was looking for. This is not as smooth a solution as having a folder-wide search field available from the browser, but given the rarity of these searches, an in-browser solution just isn’t worth the effort.
One other thing I typically do when I create a new PNotes folder for a project: I replace the generic folder icon with a Moleskine notebook icon like one of these:
I found one of these, at a larger size, by doing a Google Image search and made the others by fiddling with the band color in Acorn. It’s nice to have the PNotes folder stand out.
A reminder on how to change the icon of a folder:
- Open the image you want to use and copy it to the clipboard.
- In the Finder, do a Get Info on the folder you want to change.
- Select the folder’s icon at the top of the Get Info window by clicking on it.
- Paste. The generic folder icon should be replaced by the image on the clipboard.
This post has turned out to be a bit more miscellaneous than I’d planned.
The no-server notes wiki
February 10th, 2010 at 4:32 pm
I’ve just pushed a new version of my unnamed no-server notes wiki to its GitHub repository. Notes can now be organized in subdirectories instead of all being at the top level. Here’s the README.
This is a no-server personal wiki system that I created to keep track of project notes for work. I’ve put it here because it may be useful to others.
Goals
This is what I want:
- A self-contained file or folder of files that includes everything needed to write and view the notes. I want it to be easy to copy from one computer to another and to archive to DVD. This eliminates most of the available wiki systems, which store everything in a central database.
- The notes themselves to be written in Markdown rather than some specialized wiki markup. I write everything in Markdown and don’t want to shift context when switching from notes to a report. In fact, I’d like to be able to copy directly from my notes—markup included—when writing a report.
- To write the notes in my text editor of choice rather than in an HTML text input box or a word processor. Currently, that editor is TextMate, but TextMate itself isn’t the point. The point is to take advantage of the comfort I feel working in my normal editor. There’s a reason old Unix hackers like to do everything in Emacs or vi; it’s just more efficient to do all your text work in one environment.
- To be able to change the visual style of the notes as my needs or tastes change.
- To create new notes quickly and easily.
Requirements
Apart from what’s in the repository, you’ll need
- Python. The two build scripts,
buildPage.pyandbuildNotesList.py, are written in Python. - GNU make. The build scripts are controlled by a makefile.
- A Markdown processor. I use a self-customized version of Fletcher Penney’s MultiMarkdown. Whatever you use, you’ll have to provide the name of that command on Line 16 of
buildPage.py. - A SmartyPants processor. I use Gruber’s SmartyPants. Again, you’ll have to provide the name of that command on Line 16 of
buildPage.py.
If you need to include mathematical formulas in your notes, you should consider installing Davide Cervone’s jsMath. Once you’ve installed it, you can activate jsMath in the notes by uncommenting Line 10 of the header.tmpl file and adjusting the jsmathpath variable in the project.info file to point to jsMath’s easy.js file.
File structure
The top level of the notes directory contains all the support files, that is, all the files that are distinct from the notes themselves. These files are:
header.tmpl, the HTML template file with all the common code above the content.footer.tmpl, the HTML template file with all the common code below the content.project.info, a file of project-specific data, including the project name and number, the list of contacts (including links to Address Book entries if you’re on a Mac), and thefile://URI for the top-level directory.notes.css, the style file for browsing.notes-print.css, the style file for printing.styleLineNumbers.js, a pair of JavaScript functions that improve the formatting of source code.buildPage.py, a Python script that combines a Markdown input file with the template files and produces a single HTML file.buildNotesList.py, a Python script that searches the directory (and subdirectories) for notes files and generates a list of links to all the notes for display in the sidebar.Makefile, the makefile that controls the build scripts.
Notes files contain the actual content. These files should all have the extension .md and can be in both the top-level directory and in subdirectories. Two sample notes files are included: aa-overview.md in the top-level directory, and testing1.md in the Lab subdirectory.
Creating notes
As mentioned above, notes are just plain text files written in Markdown and saved with an .md extension. The first line will be the note’s title and will appear in the sidebar.
I use ATX-style headers, with hash marks indicating the header level, and I start each file with a first-level header, like this:
# Overview #
The build system is smart enough to get rid of the hash marks when making up the sidebar.
Notes files in subdirectories appear with greater indentation under the name of the directory—like an outline. Within each directory, the notes are ordered alphabetically according to their file names, so you can rearrange the order in which the notes appear in the sidebar by changing the file names without changing their content. At present, there’s no way to change the order of the subdirectories.
Executing make from the top-level directory will generate all the HTML pages, which can be opened with any browser. Subsequent executions of make will generate only those pages whose .md files are new or have been modified. Executing make clean will erase all the HTML files, but will not touch the .md files.
Editing notes
You can, of course, open any .md file in any text editor to make changes. If you’re using TextMate on a Mac, there’s a faster way: click the Edit in TextMate link in the side bar to instantly open the .md file in TextMate—no need to switch to the Finder, open the folder, and double-click the file icon. If you’re a BBEdit user, you can do the same thing, but you’ll probably want to change the name of the link. It’s on Line 33 of header.tmpl.
More details
I wrote a three-part series of blog posts describing this system and its scripts, here, here, and here. The scripts have changed since then, but the basic ideas are the same.
License
This work is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported License. Do what you want with it, but provide a link back to either my blog posts or to my repository.
HTML notes
January 14th, 2010 at 11:12 pm
Every once in a while, I spend a little time Googling to see if someone has made a personal wiki system—or any wiki system, really—that will work better for my project notes than the home-grown system I developed a couple of years ago. When I took one of those trips around the internet last week, I returned, as always, empty handed and with a growing sense that I was never going to find what I was looking for. So I’ve decided to put a little effort into my existing system and make it easier to use.
I wrote about this note-taking system, a serverless wiki, in a series of three posts back in 2008. The first of those posts described what I wanted out of the system, and the latter two posts went into how I use it and some details of the programming. At the risk of being repetitive, this is what I want in a personal wiki:
- A self-contained file or folder of files that includes everything needed to write and view the notes. I want it to be easy to copy from one computer to another and to archive to DVD.
- The notes themselves to be written in Markdown. I write everything in Markdown and don’t want to change.
- To write my notes in my text editor of choice. Currently, that editor is TextMate, but TextMate itself isn’t the point. The point is to take advantage of the comfort I feel working in my normal editor.
- To be able to change the visual style of the notes as my needs or tastes change.
- To create new notes quickly and easily.
Were it not for Items 2 and 3, I’d be using VoodooPad. Were it not for Items 3 and 4 (and a small incompatibility with Safari), I’d be using TiddlyWiki or one of its offshoots. But I’m not interested in compromising on these things, so it looks like I’ll be sticking with my self-made system. Which works, but could use some polish and a new feature or two.
To that end, I did a little code cleanup, put it under revision control, and set up a repository for it on GitHub in anticipation of making some improvements over the next few weeks. I want to:
- Add a hierarchical structure to the notes so they can be categorized within a project. A flat structure is fine for many projects, but I’ve found that the notes for bigger projects start getting cluttered and hard to manage without the ability to gather notes into subfolders.
- Create a TextMate bundle to automate common actions, like making a new note from an internal link. This may need to be in a separate repository.
In addition, I may change the build system that drives the conversion of notes from Markdown (for writing) to HTML. Currently, I’m using make, which has the advantage of ubiquity, but which also has a clumsy syntax that I’ve never felt confident in using. I know there are several alternatives, but I don’t know enough about them yet to choose among them.
I probably won’t write any more about it until I think these improvements are complete, but you can follow the repository if you want to track my progress.