GitNoted is a simple document server that works with Github Wiki or Gollum to serve foot notes for external web sites just by adding a small script tag.
- JavaScript tag
- Writing notes
- Running server with Github Wiki
- Running server with other git repositories
- Deploying to Heroku
- Server usage
You can find the JavaScript code on lib/git_noted/public/js/gitnoted.js. This file will be served as /js/gitnoted.js from the GitNoted server. You can import it using <script> tag as following.
<!-- GitNoted depends on jQuery -->
<script src="https://code.jquery.com/jquery-3.1.1.min.js"
integrity="sha256-hVVnYaiADRTO2PzUGmuLJr8BLUSjGIZsDYGmIJLv2b8="
crossorigin="anonymous"></script>
<!-- GitNoted -->
<link rel="stylesheet" type="text/css" href="http://localhost:4567/css/gitnoted.css" />
<script type="text/javascript" src="http://localhost:4567/js/gitnoted.js"></script>
Please replace http://localhost:4567 to point your GitNoted server (see bellow).
Once the JavaScript tag is set up, you can add following <div class="gitnoted" data-labels="label,label,..."> tags your HTML to embed notes. Here is an example:
<div class="gitnoted" data-labels="purpose:test,message:hello"></div>
data-labels is used to search notes by labels. Notes that include all of them match.
Edit mode must be Markdown. Other formats are not supported.
In the body of a page, you need to include :label: label,label,label,... line at the beginning or at the end. Example:
# My first wiki page
Hello!
---
:label: purpose:test,message:hello
Prepare following information first:
- Domain names (and ports) of your website that embeds notes. You can have multiple web sites. Here uses
example.comandlocalhost:8080as an example. - Repository URL of a Github Wiki. Format of the URL is
https://github.com/<user>/<repo>.wiki.gitwhere "<user> and <repo> are your repository's username and repository name.
This command starts a server on http://localhost:4567:
$ gem install gitnoted
$ gitnoted "https://github.com/frsyuki/gitnoted.wiki.git" \
./repo \
-a example.com -a localhost:8080 \
-h localhost -p 4567
If your repository is private, you also need to set GITHUB_ACCESS_TOKEN environment variable. You can create a token on your account configuration page. Example:
$ gem install gitnoted
$ export GITHUB_ACCESS_TOKEN=abcdef0123456789abcdef0123456789abcdef01
$ gitnoted \
"https://github.com/frsyuki/my_secret_repository.wiki.git" \
./repo \
-a example.com -a localhost:8080 \
-h localhost -p 4567
Instead of using Github Wiki, you can use any git repositories that contain files named <name>.md. You can use your text editor or tools such as Gollum to push .md files.
To start GitNoted for those git repositories, prepare following information:
- Domain names (and ports) of your website that embeds notes. You can have multiple web sites. Here uses
example.comandlocalhost:8080as an example. - Repository URL of the git repository. It should provide http access (ssh is not supported at this moment).
- Username and password of the git repository. You need to set them to GIT_USERNAME and GIT_PASSWORD environment variables.
This command starts a server on http://localhost:4567:
$ gem install gitnoted
$ export GIT_USERNAME=myname
$ export GIT_PASSWORD=topsecret
$ gitnoted \
"https://github.com/frsyuki/my_secret_repository.wiki.git" \
./repo \
-a example.com -a localhost:8080 \
-h localhost -p 4567
You can create a new Heroku application using this command:
$ gem install heroku
$ heroku create --buildpack https://github.com/heroku/heroku-buildpack-multi.git
Or, you can use your existent Heroku application:
$ heroku create buildpacks:set https://github.com/heroku/heroku-buildpack-multi.git --app=your_app_name
Then, you need to put 4 files to the application.
Put a gitnoted command in your Procfile with $PORT variable as the port number. Here is an example:
web: bundle exec gitnoted "https://github.com/frsyuki/gitnoted.wiki.git ./repo -a example.com -h 0.0.0.0 -p $PORT
source "https://rubygems.org"
ruby "2.4.0"
gem "gitnoted"
https://github.com/ddollar/heroku-buildpack-apts
https://github.com/heroku/heroku-buildpack-ruby
cmake
pkg-config
$ gitnoted [options] <git url> <local path to store>
options:
-a, --allow-origin DOMAIN[:PORT] Allow cross-origin resource sharing (CORS) from this domain (can be set multiple times)
-h, --host ADDRESS Bind address (default: 'localhost')
-p, --port PORT Port (default: 4567)
-e, --extra-app PATH.rb Add an extra Sinatra application
-i, --interval SECONDS Interval to update the git repository
--threads MIN:MAX Number of HTTP worker threads
environment variables:
GIT_USERNAME Git username
GIT_PASSWORD Git password
GITHUB_ACCESS_TOKEN Github personal API token
GitNoted
Author: Sadayuki Furuhashi
License: MIT