We've had some reports (#1342, #1809) of `rdoc` not being installed
in some environments, causing Gollum to error in unpleasant ways.
This isn't an issue that's unique to Gollum, and I don't think `rdoc`
should actually be a hard dependency of this project. But since we can
side-step the issue by requiring `rdoc`, something that most users who
install Gollum via RubyGems would already have installed, I don't think
this is a horrible solution.
* Ensure example git repos are valid
It was reported in #1817 that the `lotr_migration.git` repository we use
in `test/test_migrate.rb` is not a valid git repository on when clone,
causing the test suite to fail when run locally.
The reason is because there is no `.git/refs` directory, meaning it's
not really a valid git repository at all. I noticed that the `empty.git`
example repository has the same problem.
This commit simply ensures that the directory structure of these example
repositories are persisted in git.
* Run `test_migrate` tests on CI
Now that we've resolved the issue with the invalid git repository in the
parent commit, we can run all of the tests in our CI environment.
* Use `Minitest::Test`
`Test::Unit` is deprecated, and we can switch to `Minitest::Test` with
almost no side effects.
This commit does all of the work required to make Minitest tests run
with Gollum's existing test helpers.
* Change Minitest output format
- The `DefaultReporter` seems to have cleaner output than what we had
before.
- `color: true` ensures things are colorized. It's pretty nice.
* Tweak test formatting; fix order-dependent failure
The order-dependent failure has been been commented in code.
After manually bisecting the test suite, I was able to determine that
the template cascade tests were leaving the `@@template_priority_path`
set to an overridden value in tests run afterward.
* Tweak setting initialization
I could not see a meaningful reason behind calling `forbid` so early in
the settings initialization block. But moving the `forbid` call until
later resolved this issue.
In the real world, I don't see how this would cause issues. But I found
that calling `forbid` when `wiki_options[:allow_editing]` was set to
false caused order-dependent test errors where Sprockets would end up
being badly configured and left without an initialized
`Sprockets::Environment` object, which is required by the
`sprockets-helpers` gem to resolve asset paths.
The test that would cause errors is also in this commit diff. I've
updated it to be a bit more readable.
I also took this opportunity to review and clean up the `@allow_editing`
assignment, which seemed a bit obfuscated.
* Update migration script to test run warnings
When running the entire test suite, many warnings would be output:
/Users/bw/Projects/gollum/test/test_migrate.rb:37: warning: already initialized constant HYPHENATE
/Users/bw/Projects/gollum/test/test_migrate.rb:37: warning: previous definition of HYPHENATE was here
/Users/bw/Projects/gollum/test/test_migrate.rb:37: warning: already initialized constant PAGE_FILE_DIR
/Users/bw/Projects/gollum/test/test_migrate.rb:37: warning: previous definition of PAGE_FILE_DIR was here
/Users/bw/Projects/gollum/bin/gollum-migrate-tags:91: warning: already initialized constant REPO
/Users/bw/Projects/gollum/bin/gollum-migrate-tags:91: warning: previous definition of REPO was here
/Users/bw/Projects/gollum/bin/gollum-migrate-tags:236: warning: already initialized constant TREE
/Users/bw/Projects/gollum/bin/gollum-migrate-tags:236: warning: previous definition of TREE was here
/Users/bw/Projects/gollum/test/test_migrate.rb:37: warning: already initialized constant PAGE_FILE_DIR
/Users/bw/Projects/gollum/test/test_migrate.rb:37: warning: previous definition of PAGE_FILE_DIR was here
/Users/bw/Projects/gollum/bin/gollum-migrate-tags:91: warning: already initialized constant REPO
/Users/bw/Projects/gollum/bin/gollum-migrate-tags:91: warning: previous definition of REPO was here
/Users/bw/Projects/gollum/bin/gollum-migrate-tags:236: warning: already initialized constant TREE
/Users/bw/Projects/gollum/bin/gollum-migrate-tags:236: warning: previous definition of TREE was here
While it's unlikely that end users would ever see these warnings, as
they'd only be running the migration script once, they will always be
shown in our local test runs and CI run output.
So instead of using constants in our migration script, I change the
script to use class variables instead. This should not effect the
functionality of the migration script whatsoever.
* Use `File.exist?` instead of `File.exists?`
In Ruby 3.x, `File.exists?` is deprecated and outputs a warning.
* Improve "allow editing" tests
While making changes to the test suite, I ran into some issues with
these tests failing on occasion.
I added some setup and teardown to help with this.
But one thing I did notice is that the word "Upload" appears in the
response body whether uploading is enabled or not, so I made these
assertions more specific to the HTML rather than other places the word
"Upload" might appear (which is related to Critic Markup).
* Do not attempt to modify frozen strings
Using `#gsub!` here now results in an error. I am not entirely sure why
this hasn't happened before, but the error is straightforward:
FrozenError: can't modify frozen String: "Author %{author} is from %{location}"
/home/runner/work/gollum/gollum/lib/gollum/views/helpers/locale_helpers.rb:45:in `gsub!'
/home/runner/work/gollum/gollum/lib/gollum/views/helpers/locale_helpers.rb:45:in `fill_argument_content'
/home/runner/work/gollum/gollum/lib/gollum/views/helpers/locale_helpers.rb:37:in `block in autofill'
/home/runner/work/gollum/gollum/lib/gollum/views/helpers/locale_helpers.rb:33:in `each'
/home/runner/work/gollum/gollum/lib/gollum/views/helpers/locale_helpers.rb:33:in `map'
/home/runner/work/gollum/gollum/lib/gollum/views/helpers/locale_helpers.rb:33:in `autofill'
/home/runner/work/gollum/gollum/lib/gollum/views/helpers/locale_helpers.rb:35:in `block in autofill'
/home/runner/work/gollum/gollum/lib/gollum/views/helpers/locale_helpers.rb:33:in `each'
/home/runner/work/gollum/gollum/lib/gollum/views/helpers/locale_helpers.rb:33:in `map'
/home/runner/work/gollum/gollum/lib/gollum/views/helpers/locale_helpers.rb:33:in `autofill'
/home/runner/work/gollum/gollum/lib/gollum/views/helpers/locale_helpers.rb:21:in `t'
/home/runner/work/gollum/gollum/test/gollum/views/test_locale_helper.rb:95:in `block (4 levels) in <top (required)>'
`#gsub!` attempts to modify a string in-place, which does not work when
a string is frozen. It seems that in some Ruby environments, strings
from YAML files are frozen.
* Fix another order-dependent test failure
Very occasionally, this test fails due to `Precious::App` settings set
in previous tests. You can reproduce this failure using this seed:
bundle exec rake TESTOPTS="--seed=42898"
* Remove explicit nokogori version requirement
* Require ruby >= 2.6, use latest JRuby
No longer needed after nokogiri's recent release, see https://github.com/gollum/gollum/issues/1779
* Add `.header-title` style
This style shows smaller text on mobile devices. It reverts back to the
`2em` size used in Primer for H1 tags.
* Use `.header-title` for all `#head` headings
This commit:
1. Updates all main templates to use the new `.header-title` class,
making these titles less disruptively large on mobile devices.
2. Centers these titles for mobile breakpoints only, re-setting them
back to left-aligned text for `md-` breakpoints and up.
Note that in `lib/gollum/templates/wiki_contentf.mustache`, the
`.header-title` is not a `#head .header-title`, so it doesn't inherit
all of the new styles added in this commit.
* Adjust padding and presentation of mobile menu
To give mobile page headers more structure, this commit adjusts the
padding to be more symmetrical. It also adds a `border-bottom` on mobile
only. In my opinion this improves readability by telling the reader,
"This is where the navigation menu ends and the page content begins."
* Recompile assets
* Fix failing spec
My changes to the header layout seem to changed where the spaces in
`last_response.body` are placed. So let's assert only that the content
is present, since that's all this test should actually care about.
* Simplify test
I came across this test because it was failing JRuby CI runs. I should
emphasize, though, that this test was only failing due do an upstream
bug in Nokogiri v1.12.5.
When I was reviewing the test, to understand why it was failing at all,
I noticed that the assertion was rather obfuscated. Specifically, we
were post-processing the entire `response.body` and using that as an
expectation.
* Use an older version of Nokogiri in our test env
This is a temporary fix. See the commit diff for more information.
* Split JRuby CI runs from MRI CI runs
We can improve the performance of our MRI test runs by not installing
Java as part of their run. (Java is only required for JRuby.)
* Use latest Ruby patch versions during CI runs
* Simplify GitHub Action workflow steps
Judging by the output in the GitHub Actions workflow UI, the `echo`
steps were not providing much value to us.
We can get rid of them to slightly increase run performance.
I've also named the other steps to make it easier to skim the Actions
workflow output.
* Remove `twitter_cldr` development dependency
This is no longer being used.
* Change GitHub Actions workflow Ruby matrix
We can drop Ruby 2.4 from our test run matrix. It is beyond EOL.
Let's add 2.7 instead.
* Add `i18n` dependency
We will use `i18n` to provide localization for Gollum's frontend. I
chose this because it's a well-supported, pretty normal Ruby library.
* Configure I18n
- Locale files will be kept in `lib/gollum/locales/[lang].yml`
- The available locales, to start, will be English (`en`).
* Add I18n interface for mustache templates
This commit adds an interface that allows mustache templates to get I18n
translation strings, transform any arguments that may be present in
them, and then render them on the frontend.
This is our first real step to getting internationalizing the Gollum
frontend.
An issue was reported (see #1721) where, in docker containers where the
`LANG` was not being set, `Precious::App` would serve Mustache templates
in an ASCII encoding. This caused templates to error out.
In the past, this would have happened in environments where `LANG` was
not set and the Gollum applciation configuration had enabled MathJax.
Now, it happens even if MathJax is disabled because of a UTF-8 character
I added to the mobile navigation menu.
Basically, we should enforce a UTF-8 encoding from now on to avoid
runtime errors related to ASCII encoding.
* fixes#1723: Github Actions Supported
- This is to switch from Travis CI which is shutting down the org version,
and the .com version, a free account is limited.
- Switch test environment variable from TRAVIS to CI to be more generic.
* Adding jruby-9.2.18.0 to matrix for github actions
I made a mistake when I made `#title` a private method. I did not see
that it was being called from `layout.mustache` to generate the
`<title></title>` tag in the `<head></head>` of each page.
This fixes my error, and adds tests so the behaviour is more explicit.
* Fix tabnav styles on #create and #edit views
The Primer CSS-provided `tabnav` styles were not being used on the Edit
and Preview tabs on the create and edit pages.
After following Primer's documentation [1], it looks like we were using
the `aria-current` attribute incorrectly. Dynamically adding/removing
this attribute on the selected tab fixes the issue.
[1]: https://primer-css-git-next-inputs.primer.now.sh/css/components/navigation#tabnav
* Recompile static assets
It is more semantic to use a `<button>` tag in the place of an `<a>`
when there is no other page being linked to. In this circumstance, we're
using JavaScript to present a modal to the user on click.
This change makes the "Upload" and "Rename" buttons appear in the
browser's tab index.
There was a display issue, where navbar items's outline styles were
being cut off due to the parent `<nav>` element's margin and padding.
Fortunately, we can do away with the navbar wrapper div entirely. It was
not doing anything important except defining its children as
`TableObject` items. But we can just do this on the `<nav>` itself.
If the user has edit permissions, the "History" button is shown in a
button group with "Edit" and "Rename". If the user does not have edit
permissions, it's shown by itself.
This commit also renames the label from "Page History" to "History".
* Change footer and footer container spacing
This commit:
1. Removes the Primer `my-md-0` spacing from the `#wiki-footer`
container.
This gives it margins along the Y axis, spacing it out from
the sidebar and main wiki content containers on `md` and larger
screens.
2. Adds `px-4` padding to the `#footer-content`. which makes the
This makes the footer content inset the same way that sidebar
content is. This makes the content look more uniform on mobile
devices, when the sidebar and footer are presented one before
the other.
* Change spacing behaviour of `#wiki-sidebar`
To make `#wiki-sidebar` and `#wiki-footer` more similar, we can make
sure `px-4` padding is applied to the `-content` container, rather than
the outer container.
* If navbar is too wide, use overflow-x: scroll
* Add initial mobile nav menu
* Use CSS classes instead of IDs for jQuery events
* Change content x-axis padding for mobile devices
* Recompile assets for mobile menu feature
* Filter _Template content. Resolves#1603 and #1640.
* Introduces a Gollum::TemplateFilter class with methods to easily add _Template Filters.
* Adds support for relative _Template pages with fallback to _Template in root.
POST requests are blocked when running in --no-edit mode so using POST
prevents compare being available (see #1546).
Change the history view form to use "get" as the form method and change
the routing in app to accept get requests for both forms of compare. The
order of the compare routes is switched to make the more specific form
checked first to prevent all requests being handled by the less specific
form.
The original selector "#wiki-content h1" matches multiple times
when the page content has h1 headers, resulting in multiple notice
in a page, and what is worse, "$('#gollum-flash').fadeOut()" works
only for the first one.
* Pagination for history and latest changes
* New footer for historical pages
* Fix pagination on history view.
* Do not directly use git adapter
* History view: allow selecting from different pages
* Use log_pagination_options to determine latest changes parameters
* Fix JS pageFullPath
* Improve RTL support with updated ACE 1.4.4
* Implement direction switch button
* RTL support on rendered pages
* Fix ace editor modes
* Fix language definitions
* Remove all references to page_file_dir. Use new method signature for Wiki#page. Refactor helpers.
* Use write_file for uploads
* Refactor /pages route
* Improve editor buttons: insert markup at the correct position
* Center cursor after replacing text.
* Reimplement keyboard shortcuts for ace.
* Add break_line and whole_line to all language definitions
* Implement a better unordered list function.
* CSS to SCSS
* Use sprockets
* Use Sprockets helpers
* Fix gollum.editor.js error when changing language
* Add keybinding files required by ace and some ace ext files that are required or might be useful.
* Move app paths to /gollum namespace, add route helpers for view templates
* Use path helper for links in page view
* Use path helper methods in javascript assets
* Refactored sprockets helpers for mustache
* Remove debugging
* CSS to SCSS
* Fix travis
* Use sprockets
* Use Sprockets helpers
* Fix gollum.editor.js error when changing language
* Fix fileview styles, use same style as Pages View.
* Add keybinding files required by ace and some ace ext files that are required or might be useful.
* Fix page list for files that have regexp special chars.
The page list collection logic was using the filename without any
scaping to create a regexp. This not only breaks for some names it might
even be a security problem by introducing bad regular expression as
filenames.
* Add another video to README.
* Test on Ruby 2.4
* Pass non-empty commit author details in transliteration test
Empty name or email are not allowed by libgit2 and cause a test failure
when the test suite is run against rugged_adapter.
* Solve bug when folder contain non-ascii character
When you create a file in a folder with non-ascii character, for exemple "Réseau", after creating the page, it throwed an "URI::InvalidURIError", given the fact that the url returned was "/Réseau/H%C3%A9y", only the part with the name of the file was correctly encoded.
So I propose to encode every part of the url to solve this issue
So I just
* readme: Use --document in place of deprecated options
* Release 4.1.0
* Skip tests for transliteration for adapters different than grit
* Fix date. Closes#1211
* Set bar_side for versioned pages. Closes#1226
* Update gemijione dependency. Closes#1227
* Release 4.1.1
* Update Mousetrap and use new 'mod' helper
Since version 1.4, a generic 'mod' helper can be used for cross
platform shortcuts. I updated Mousetrap to latest v1.6.1 and
used 'mod+s' instead of ['ctrl+s', 'command+s'] for the editor's
keyboard shortcut.
See https://craig.is/killing/mice#api.bind.combo
* Replace editor's content editor with Ace Editor
* Bundle ace 1.2.5
* Give the ace editor body a name
* Changeing edit mode now changes Ace's editor mode
* Move Ace interface into gollum.editor.js and implement drag and drop uploading
* Make editor bottons work (mostly)
* Fix edit mode mapping
* Fix mode selection for empty editor
* Make the ace editor vertically resizable
* Add org-mode and reStructuredText mode mapping
* Add missing jquery.resize.js
* Change keybinding from vim to emacs
* Makes ace resizable on Chrom
* Fix accidental change of resize
* Add keyboard selector and fix commit message updating
* Add visual aid in editor to signal unavailable formats
* Hide line number by default
Permission checking was spread across `post` action handlers instead of inside the `before` to normalize between `get` and `post` action handlers and be more explicit.
When you create a file in a folder with non-ascii character, for exemple "Réseau", after creating the page, it throwed an "URI::InvalidURIError", given the fact that the url returned was "/Réseau/H%C3%A9y", only the part with the name of the file was correctly encoded.
So I propose to encode every part of the url to solve this issue
So I just
The page list collection logic was using the filename without any
scaping to create a regexp. This not only breaks for some names it might
even be a security problem by introducing bad regular expression as
filenames.
From [RubyGems](https://rubygems.org/gems/github-markdown/versions/0.6.9):
> THIS GEM IS NOT MAINTAINED AND NOT SUPPORTED.
Also, the GitHub repository, maintained by GitHub, was removed.
The link is now a redirect, it doesn't point to the GFM page anymore.
Permission checking was spread across `post` action handlers instead of inside the `before` to normalize between `get` and `post` action handlers and be more explicit.
Use Gollum::Page#last_version instead of Gollum::Page#versions in the
cases identified in #1087:
* In Precious::App#show_page_or_file
* In Precious::Views::Page#author
* In Precious::Views::Page#date
The existing 'files_folders' test only covered the /Mordor subdirectory,
which does not include a diverse enough set of pages and folders to account
for the new rendering logic.
This test uses the results from the root of the lotr.git example repository
as it exists at this point in time. The mock '@results' are not passed as a
sorted array in order to test the sorting logic.
The existing 'files_folders' test has been renamed to 'files_folders from subdir'
because the 'files_folders' function should be tested in a situation when
viewing /pages from a subdirectory to ensure proper functionality.
Previously, the 'All Pages' view was not sorted alphabetically. We need
to sort on the lowercase version of the page names so that lowercase
names do not end up at the bottom of the list and are instead mixed in
alphabetically, as they should be.
Patches test/test_latest_changes_view.rb to include changes needed to
test alphabetical sorting.
Changed to resolve intermittent errors where I'd see the following in my logs:
```text
ERROR -- : app error: undefined method `wiki_options' for Precious::App:Class (NoMethodError)
ERROR -- : /home/gollum/production/releases/20141229-172128/vendor/bundle/ruby/2.0.0/gems/gollum-3.1.1.1anchor4/lib/gollum/editing_auth.rb:10:in `call'
ERROR -- : /home/gollum/production/releases/20141229-172128/vendor/bundle/ruby/2.0.0/gems/rack-protection-1.5.3/lib/rack/protection/xss_header.rb:18:in `call'
...
```
I suspect this is the case for Sinatra applications that host instances of Gollum using its `map` feature, as this reflects the production setup we're using it in. Calling @app.settings.wiki_options uses the app instance that gets passed into Precious::EditingAuth, thereby ensuring that we're getting a Gollum instance all the time.
The previous test implementation was dependent on the git configuration:
renames = copies
It could then pass on a computer with that config but not passe on
a different developpeur computer who could have a different git configuration.
That new implementation is testing the same behaviour but at a lower
level and is not dependent on the git configuration anymore.
trying to remove backreferences after doing transformations on text
(Bolding, Italicizing, etc.). This can be fixed by first escaping the
string to be transformed and then unescaping it afterwards.
Storing all uploaded files in a single directory kinda sucks when you've got
a largish wiki, or the possibility of filename collisions. With this patch,
though, you can set `:per_page_uploads => true` in your wiki settings and
have the file uploaded to a directory named for the page you were on when
you clicked 'Upload'.
Adjusted the version specs on the two gems that explicitly state they are
SemVer compliant, and fixed up the one dependency that correctly *could* have
used ~> but didn't.
Adds an :allow_uploads wiki option, an --allow-uploads flag to
bin/gollum, an "Upload" button with a file upload dialog, and a
handler to commit uploaded files into the repository.
:allow_uploads defaults to false, to prevent unauthenticated users
from uploading arbitrary files into the repository (albeit only in
the uploads directory).
This code is based on the patch from @l3iggs at
https://github.com/gollum/gollum/issues/694, but the handling on the
backend is completely rewritten to use the Committer infrastructure.
* Also fixes renaming a file from a subdirectory moves it to the root.
* Add context info option to dialog, used in the new dialog
* Added CSS to support new context option for dialogs
* Fix /pages view messing up directory creation in new
* Removed the Edit and Rename buttons from historic view
(statically hosted content in the images/ folder returns 404s)
(the problem was all content in javascript, css, and images folders was hard-coded to return 404s)
The test passes when verified manually using bin/gollum. Without a running server the test
will fail so it has been commented out. If there's an easy way to mock Rack::Server
then the test can be restored.
E: There are problems and -y was used without --force-yes
before_install: 'sudo apt-get install -y asciidoc' returned false.
Done. Build script exited with: 1
Page link may contain duplicate starting forward slashes.
//page points to http://page/ when what we want is
/page pointing to http://localhost:1234/page
Example of absolute path to local file.
```html:/home```
Example of relative path to local file.
```html:home```
1.8.7 string fix. 's'[0..0] instead of 's'[0]
Fix regex.
Add absolute and relative tests.
The expected output from the tests differs only in newlines.
git diff makes it seem like everything changed. bzr qdiff has a better default diff. git doesn't do per char diffs.
Revert "New pygments has issues."
This reverts commit 2dd41cbfac.
Exact matching of requested pages
- /page is no longer the same as /a/page
- Deleting /page only deletes /page (before it would delete /a/page instead of /page)
- Edit currently breaks the unit tests if exact matching is enabled
- Fix redirect on create
- Add @giga's checked_dir = '' fix https://github.com/giga/gollum/commit/936958b47324a09c683cb90a2560484b47e09529
- Fix create unit test
Previously, a page created with the 'New' button would get all of its
spaces turned into the + symbol when submitted, which Gollum would then
convert into "-plus-" in the title. So, for example, a request to create
a page called "Test page" would instead get "test plus page".
This change changes + to - in the parameter received by /create/.
Update ace.
Replace pagedown with sundown. Live preview is now able to render markdown identical to regular gollum by leveraging the same library.
Thanks to @kripken for explaining how to best use emscripten for sundown.
Although the standard formula delimiters for latex formulas is currently
`\(` and `\[`, the `$` syntax has an advantage from the point of view of
writing speed, very important if we intend to use *gollum* as a writing
tool.
The code includes support for escaping of the `$` symbol by using the
gollum syntax `'`.
Fixed an issue of latex inline formulas not aligning correctly with
the text. The fix is a ruby translation of the Perl code described in
http://tex.stackexchange.com/questions/44486/pixel-perfect-vertical-alignment-of-image-rendered-tex-snippets.
This code calculates the alignment of the generated image depending on
the image size and the size of the white space between the formula and
the margins of the image.
The alignment now is nearly perfect, however the new rendering comes
with a performance impact because of the increased number of operations.
To reduce this impact, the generated images and calculated values for
the alignment are now cached in `~/.cache/gollum`. The caching is done
per formula and not per page, thus avoiding caching the same formula
twice.
The Readme and tests have been modified accordingly with the new tool
requirements and expected markup.
Update Ace.
Fix CSS for new Ace.
Prevent flickering of toolpanel.
Add GitHub theme for Ace.
Remove gutter in static highlight ext.
Update languages for Ace.
Use darkness div to dim the background when the comment window is active.
Set CSS in batch to avoid unnecessary reflows.
Use debouncing to efficiently resize the window.
Eliminate previewSetter in favor of redefining the previewSet function.
asciidoc's representation of section identifiers interferes with
Gollum's page linking. This disables Gollum's page link tag
extraction for asciidoc files.
Adds "apt-get install -y asciidoc" to .travis.yml so tests pass
on @travis-ci.
asciidoc's representation of section identifiers interferes with
Gollum's page linking. This disables Gollum's page link tag
extraction for asciidoc files.
**Please read the [CONTRIBUTION GUIDELINES](https://github.com/gollum/gollum/blob/master/CONTRIBUTING.md) before submitting!**
If your have problems using or installing the software which stem from bugs in the software or a lack of documentation, we are always happy to help out! However, **for ordinary usage questions, please consider asking elsewhere**, for instance on [StackOverflow](http://stackoverflow.com/questions/tagged/gollum-wiki).
**Describe the bug**
A clear and concise description of what the bug is.
**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
**Expected behavior**
A clear and concise description of what you expected to happen.
**Screenshots**
If applicable, add screenshots to help explain your problem.
**Environment Info**
Always include the output of the `gollum --versions` command (NB: `versions` in plural).
If your have problems using or installing the software which stem from bugs in the software or a lack of documentation, we are always happy to help out! However, **for ordinary usage questions, please consider asking elsewhere**, for instance on [StackOverflow](http://stackoverflow.com/questions/tagged/gollum-wiki).
Gollum supports [custom macros](https://github.com/gollum/gollum/wiki#macros) for the creation of additional wiki markup tags. Please **do not** use this tracker to request macros specific to your situation. However, if you have or are working on a macro that you think may be useful to more users, you can share it as a GitHub [gist](https://gist.github.com) and link to it in the [wiki](https://github.com/gollum/gollum/wiki/Custom-macros).
Before submitting an issue, **please carefully look through the following places** to make sure your problem is not already addressed:
1. The issue tracker.
1. The [README](https://github.com/gollum/gollum/blob/master/README.md).
1. The project's [wiki](https://github.com/gollum/gollum/wiki).
Security vulnerabilities can be reported directly to the maintainers using these GPG keys:
You can triage issues which may include reproducing bug reports or asking for vital information, such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to [subscribe to gollum on CodeTriage](https://www.codetriage.com/gollum/gollum).
## Opening a Pull Request
Pull Requests fixing bugs, implementing new features, or updating documentation and dependencies are all very welcome! If you would like to help out with the project, you can pick an open issue from the issue tracker. We're more than happy to help you get started! Here's how you can proceed:
1. Fork and clone Gollum.
2. Create a thoughtfully named topic branch to contain your changes.
3. If you haven't installed dependencies yet, navigate to your clone and execute:
```
[sudo] bundle install
```
4. Hack away.
5. Add your own tests and make sure they're all still passing.
6. If some of your changes deserve a mention on Gollum's home page, edit the README accordingly.
7. If necessary, rebase your commits into logical chunks, without errors.
8. Push the branch to your fork on GitHub.
9. Create a pull request for Gollum.
**Notes:**
* Do not change Gollum's version numbers, we will do that on our own.
### Running tests
1. Install [Bundler](http://bundler.io/).
2. Navigate to the cloned source of Gollum.
3. Install dependencies:
```
[sudo] bundle install
```
4. Run the tests:
```
bundle exec rake test
```
To profile slow tests, you can use `bundle exec rake test TESTOPTS="--verbose"`.
### Working with test repositories
An example of how to add a test file to the bare repository lotr.git.
```
mkdir tmp
cd tmp
git clone ../test/examples/lotr.git/
git log
echo "test" > test.md
git add .
git commit -am "Add test"
git push ../lotr.git/ master
```
## Updating static assets
This is necessary whenever changes have been made to the assets in `lib/gollum/public/gollum/javascript` (mostly SASS, CSS, and JS files), to ensure the changes are also present in the [released](#releasing-the-gem) version of the gem. Steps:
* Fix broken history button when viewing historical deleted file. (@NikitaIvanovV)
* Fix: non-ascii characters in page names are not rendered correctly in the preview tab of the "Edit" page. #1739 (@yy0931)
* Fix: anchors and header display on JRuby. #1779
# 5.2.3 / 2021-04-18
* Fix bug preventing page titles from being displayed
# 5.2.1 / 2021-02-25
* Fix include call to a missing asset (@benjaminwil). This caused slow first page loads on JRuby.
# 5.2 / 2021-02-24
* Improved styling and Primer upgrade (@benjaminwil)
* Add redirect to rename commit (@ViChyavIn)
* Updated dependencies
* Bugfixes
# 5.1.2
* Guard against malicious filenames in breadcrumbs
# 5.1
* Bugfixes
* Add autosave feature (#1576)
* Add Add quick access to diff of each commit in the history
# 5.0 / 2020-03-17
This is a major new release that introduces many new features, bugfixes, and removes major limitations. See [here](https://github.com/gollum/gollum/wiki/5.0-release-notes) for a list of changes.
**Note**: due to changes to the way in which Gollum handles filenames, you may have to change some links in your wiki when migrating from gollum 4.x. See the [release notes](https://github.com/gollum/gollum/wiki/5.0-release-notes#migrating-your-wiki) for more details. You may be find the `bin/gollum-migrate-tags` script helpful to accomplish this. Also see the `--lenient-tag-lookup` option for making tag lookup backwards compatible with 4.x, though note that this will decrease performance on large wikis with many tags.
Many thanks to all the users who have provided feedback, and everyone who has chipped in in the development process!
Many of these changes have been made possible by removing the default grit adapter in favour of the new [rugged adapter](https://github.com/gollum/rugged_adapter).
# 4.1.4 /2018-01-10
* Depend on new version of gollum-lib that relies on a patched version of sanitize, which solves a vulnerability (CVE-2018-3740). See https://github.com/gollum/gollum-lib/pull/296.
# 4.1.3 /2018-17-09
* Solves a vulnerability in the File view and All Pages view that would allow XSS.
# 4.1.2 /2017-08-07
* Lock to a newer version of gollum-lib to avoid installing an outdated and vulnerable dependency (nokogiri) on ruby 2.0. See https://github.com/gollum/gollum-lib/pull/279. Note: this breaks semantic versioning so those using outdated rubies will discover the problem on update.
# 4.1.0 /2017-03-09
* Added file deletion functionality to file view
* Various performance improvements
* Emoji support
# 4.0.0 /2015-04-11
* Now compatible with JRuby (via the [rjgit](https://github.com/repotag/rjgit) [adapter](https://github.com/repotag/gollum-lib_rjgit_adapter))
# 3.1.1 /2014-12-04
* Security fix for [remote code execution issue](https://github.com/gollum/gollum/issues/913). Please update!
# 3.1 / 2014-11-28
* New features
* Drag-and-drop uploading in the editor [@lucas-clemente](https://github.com/lucas-clemente)
* Option `--no-edit` to disable editing from the web interface [@bambycha](https://github.com/bambycha) (#879)
* Option `--mathjax-config` to specify custom mathjax configuration [@hardywu](https://github.com/hardywu) (#842)
* Major enhancements
* Made the Gollum theme responsive [@rtrvrtg](https://github.com/rtrvrtg) (#831)
* Depends on new [gollum-lib](https://github.com/gollum/gollum-lib) `4.0.0`
* Allows specifiying [git adapter](https://github.com/gollum/gollum/wiki/Git-adapters) with `--adapter` [@bartkamphorst](https://github.com/bartkamphorst), [@dometto](https://github.com/dometto)
* Numerous bugfixes
* **NB**: please pass `--h1-title` if you do not want page titles to default to the page's filepath. See [here](https://github.com/gollum/gollum/wiki/Page-titles).
# 2.4.11 / 2013-01-08
* Numerous security issues have been fixed. Please update to `2.4.11`
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque vulputate tincidunt sollicitudin. Quisque sit amet leo sed nunc eleifend rhoncus in consectetur leo. Vivamus posuere semper convallis. Duis malesuada lacus sed erat lobortis tincidunt mattis ligula consectetur. Sed aliquam vulputate eros at euismod. Aenean egestas lorem ligula, quis faucibus turpis. Curabitur a eros in ipsum gravida ornare. Sed elementum enim vel mi scelerisque dapibus. Nulla id libero ligula, quis tempus sem. Morbi nec felis tortor, ac cursus risus. Mauris elementum tortor id lacus eleifend non lobortis tellus pharetra. Etiam posuere cursus vestibulum. $x \lt y$
Morbi tincidunt dolor vel massa dictum volutpat. Vestibulum quis nibh metus, id tincidunt nisl. Vivamus eget sem ac risus eleifend rhoncus at eu nisl. Nunc elit massa, vulputate ac gravida eget, condimentum quis justo. Integer scelerisque, libero vel consequat ultricies, eros libero sagittis libero, pellentesque bibendum quam massa ut orci. Maecenas sit amet urna eget quam aliquam posuere. Nulla facilisi. Duis imperdiet augue sit amet metus ornare et hendrerit dui feugiat. Aenean a lacus neque. Sed eu enim tincidunt dolor pharetra porttitor. Vestibulum ut felis dui, rutrum iaculis orci. Duis eu bibendum tortor. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Suspendisse mollis sagittis purus sit amet sollicitudin. Phasellus vel interdum erat.
See the [wiki](https://github.com/gollum/gollum/wiki) for extensive documentation, along with [screenshots](https://github.com/gollum/gollum/wiki/Screenshots) of Gollum's features.
## DESCRIPTION
Gollum is a simple wiki system built on top of Git that powers GitHub Wikis.
Gollum is a simple wiki system built on top of Git. A Gollum Wiki is simply a git repository of a specific nature:
Gollum wikis are simply Git repositories that adhere to a specific format.
Gollum pages may be written in a variety of formats and can be edited in a
number of ways depending on your needs. You can edit your wiki locally:
* A Gollum repository's contents are human-editable text ormarkup files.
* Pages may be organized into directories any way you choose.
* Other content can also be included, for example images, PDFs and headers/footers for your pages.
* Gollum pages:
* May be written in a variety of [markups](#markups).
* Can be edited with your favourite editor (changes will be visible after committing) or with the built-in web interface.
* Can be displayed in all versions, reverted, etc.
* Gollum strives to be [compatible](https://github.com/gollum/gollum/wiki/5.0-release-notes#compatibility-option) with [GitHub](https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis) and [GitLab](https://docs.gitlab.com/ee/user/project/wiki/#create-or-edit-wiki-pages-locally) wikis.
* Just clone your GitHub/GitLab wiki and view and edit it locally!
* With your favorite text editor or IDE (changes will be visible after committing).
* With the built-in web interface.
* With the Gollum Ruby API.
Gollum follows the rules of [Semantic Versioning](http://semver.org/) and uses
[TomDoc](http://tomdoc.org/) for inline documentation.
### SYSTEM REQUIREMENTS
Gollum runs on Unix-like systems using its default [adapter](https://github.com/gollum/rugged_adapter) for [rugged](https://github.com/libgit2/rugged). You can also run Gollum on [JRuby](https://github.com/jruby/jruby) via its [adapter](https://github.com/repotag/gollum-lib_rjgit_adapter) for [RJGit](https://github.com/repotag/rjgit/). On Windows, Gollum runs only on JRuby.
## INSTALLATION
The best way to install Gollum is with RubyGems:
### As a RubyGem
$ [sudo] gem install gollum
Ruby is best installed either via [RVM](https://rvm.io/) or a package manager of choice. Then simply:
```
gem install gollum
```
Installation examples for individual systems can be seen [here](https://github.com/gollum/gollum/wiki/Installation).
If you're installing from source, you can use [Bundler][bundler] to pick up all the
gems:
To run, simply:
$ bundle install
1. Run: `gollum /path/to/wiki` where `/path/to/wiki` is an initialized Git repository.
2. Open `http://localhost:4567` in your browser.
In order to use the various formats that Gollum supports, you will need to
separately install the necessary dependencies for each format. You only need
to install the dependencies for the formats that you plan to use.
* [Pod](http://search.cpan.org/dist/perl/pod/perlpod.pod) -- `Pod::Simple::HTML` comes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN.
See [here](https://github.com/gollum/gollum/wiki/Gollum-via-Docker) for instructions on how to run Gollum via Docker.
### Misc
See [below](#running-from-source) for information on running Gollum from source, as a Rack app, and more.
## MARKUPS
Gollum allows using different markup languages on different wiki pages. It presently ships with support for the following markups:
* [Markdown](http://daringfireball.net/projects/markdown/syntax) (see [below](#Markdown-flavors) for more information on Markdown flavors)
You can easily activate support for other markups by installing additional renderers (any that are supported by [github-markup](https://github.com/github/markup)):
By default, Gollum ships with the `kramdown` gem to render Markdown. However, you can use any [Markdown renderer supported by github-markup](https://github.com/github/markup/blob/master/lib/github/markup/markdown.rb). This includes [CommonMark](https://commonmark.org/) support via the `commonmarker` gem. The first installed renderer from the list will be used (e.g., `redcarpet` will NOT be used if `github/markdown` is installed). Just `gem install` the renderer of your choice.
To view and edit your Gollum repository locally via the built in web
interface, simply install the Gollum gem, navigate to your repository via the
command line, and run the executable:
See [here](https://github.com/gollum/gollum/wiki/Custom-rendering-gems) for instructions on how to use custom rendering gems and set custom options.
$ gollum
## RUNNING FROM SOURCE
This will start up a web server running the Gollum frontend and you can view
and edit your wiki at http://localhost:4567. To get help on the command line
utility, you can run it like so:
1. `git clone https://github.com/gollum/gollum`
2. `cd gollum`
3. `[sudo] bundle install`
4. `bundle exec bin/gollum`
5. Open `http://localhost:4567` in your browser.
$ gollum --help
### Rack
Gollum can also be run with any [rack-compatible web server](https://github.com/rack/rack#supported-web-servers). More on that [over here](https://github.com/gollum/gollum/wiki/Gollum-via-Rack).
## REPO STRUCTURE
### Rack, with an authentication server
A Gollum repository's contents are designed to be human editable. Page content
is written in `page files` and may be organized into directories any way you
choose. Special footers can be created in `footer files`. Other content
(images, PDFs, etc) may also be present and organized in the same way.
Gollum can also be run alongside a CAS (Central Authentication Service) SSO (single sign-on) server. With a bit of tweaking, this adds basic user-support to Gollum. To see an example and an explanation, navigate [over here](https://github.com/gollum/gollum/wiki/Gollum-via-Rack-and-CAS-SSO).
### Service
## PAGE FILES
Gollum can also be run as a service. More on that [over here](https://github.com/gollum/gollum/wiki/Gollum-as-a-service).
Page files may be written in any format supported by
[GitHub-Markup](http://github.com/github/markup) (except roff). The
current list of formats and allowed extensions is:
| --ref | [REF] | Specify the git branch to serve. Default: `master`. |
| --bare | none | Tell Gollum that the git repository should be treated as bare. |
| --adapter | [ADAPTER] | Launch Gollum using a specific git adapter. Default: `rugged`.<sup>2</sup> |
| --base-path | [PATH] | Specify the leading portion of all Gollum URLs (path info). Setting this to `/wiki` will make the wiki accessible under `http://localhost:4567/wiki/`. Default: `/`. |
| --page-file-dir | [PATH] | Specify the subdirectory for all pages. If set, Gollum will only serve pages from this directory and its subdirectories. Default: repository root. |
| --static, --no-static | none | Use static assets. Defaults to false in development/test, true in production/staging. |
| --assets | [PATH] | Set the path to look for static assets. |
| --css | none | Tell Gollum to inject custom CSS into each page. Uses `custom.css` from wiki root.<sup>3</sup> |
| --js | none | Tell Gollum to inject custom JS into each page. Uses `custom.js` from wiki root.<sup>3</sup> |
| --no-edit | none | Disable the feature of editing pages. |
| --local-time | none | Use the browser's local timezone instead of the server's for displaying dates. Default: false.
| --follow-renames, --no-follow-renames | none | Follow pages across renames in the History view. Default: true.
| --allow-uploads | [MODE] | Enable file uploads. If set to `dir`, Gollum will store all uploads in the `/uploads/` directory in repository root. If set to `page`, Gollum will store each upload at the currently edited page.<sup>4</sup> |
| --mathjax | none | Enables MathJax (renders mathematical equations). By default, uses the `TeX-AMS-MML_HTMLorMML` config with the `autoload-all` extension.<sup>5</sup> |
| --critic-markup | none | Enable support for annotations using [CriticMarkup](http://criticmarkup.com/). |
| --irb | none | Launch Gollum in "console mode", with a [predefined API](https://github.com/gollum/gollum-lib/). |
| --h1-title | none | Tell Gollum to use the first `<h1>` as page title. |
| --no-display-metadata | none | Do not render metadata tables in pages. |
| --user-icons | [MODE] | Tell Gollum to use specific user icons for history view. Can be set to `gravatar`, `identicon` or `none`. Default: `none`. |
| --mathjax-config | [FILE] | Specify path to a custom MathJax configuration. If not specified, uses the `mathjax.config.js` file from repository root. |
| --template-dir | [PATH] | Specify custom mustache template directory. Only overrides templates that exist in this directory. |
| --template-page | none | Use _Template in root as a template for new pages. Must be committed. |
| --emoji | none | Parse and interpret emoji tags (e.g. `:heart:`) except when the leading colon is backslashed (e.g. `\:heart:`). |
| --lenient-tag-lookup | none | Internal links resolve case-insensitively, will treat spaces as hyphens, and will match the first page found with a certain filename, anywhere in the repository. Provides compatibility with Gollum 4.x. |
| --help | none | Display the list of options on the command line. |
| --version | none | Display the current version of Gollum. |
| --versions | none | Display the current version of Gollum and auxiliary gems. |
Page file names may contain any printable UTF-8 character except space
(U+0020) and forward slash (U+002F). If you commit a page file with any of
these characters in the name it will not be accessible via the web interface.
**Notes:**
Even though page files may be placed in any directory, there is still only a
single namespace for page names, so all page files should have globally unique
names regardless of where they are located in the repository.
1. The `0.0.0.0` IP address allows remote access. Should you wish for Gollum to turn into a personal Wiki, use `127.0.0.1`.
2. Before using `--adapter`, you should probably read [this](https://github.com/gollum/gollum/wiki/Git-adapters) first.
3. When `--css` or `--js` is used, respective files must be committed to your git repository or you will get a 302 redirect to the create a page.
4. Files can be uploaded simply by dragging and dropping them onto the editor's text area when `--allow-uploads` is used.
The special page file `Home.ext` (where the extension is one of the supported
formats) will be used as the entrance page to your wiki. If it is missing, an
automatically generated table of contents will be shown instead.
### Config file
## SIDEBAR FILES
When `--config` option is used, certain inner parts of Gollum can be customized. This is used throughout our wiki for certain user-level alterations, among which [customizing supported markups](https://github.com/gollum/gollum/wiki/Formats-and-extensions) will probably stand out.
Sidebar files allow you to add a simple sidebar to your wiki. Sidebar files
are named `_Sidebar.ext` where the extension is one of the supported formats.
Sidebars affect all pages in their directory and any subdirectories that do not
have a sidebar file of their own.
**All of the mentioned alterations work both for Gollum's config file (`config.rb`) and Rack's config file (`config.ru`).**
## FOOTER FILES
## CONTRIBUTING
Footer files allow you to add a simple footer to your wiki. Footer files must
be named `_Footer.ext` where the extension is one of the supported formats.
Like sidebars, footers affect all pages in their directory and any
subdirectories that do not have a footer file of their own.
Please consider helping out! See [CONTRIBUTING](CONTRIBUTING.md) for information on how to submit issues, and how to start hacking on gollum.
## THANKS TO
## HTML SANITIZATION
For security and compatibility reasons Gollum wikis may not contain custom CSS
or JavaScript. These tags will be stripped from the converted HTML. See
`docs/sanitization.md` for more details on what tags and attributes are
allowed.
## BRACKET TAGS
A variety of Gollum tags use a double bracket syntax. For example:
[[Link]]
Some tags will accept attributes which are separated by pipe symbols. For
example:
[[Link|Page Title]]
In all cases, the first thing in the link is what is displayed on the page.
So, if the tag is an internal wiki link, the first thing in the tag will be
the link text displayed on the page. If the tag is an embedded image, the
first thing in the tag will be a path to an image file. Use this trick to
easily remember which order things should appear in tags.
Some formats, such as MediaWiki, support the opposite syntax:
[[Page Title|Link]]
## PAGE LINKS
To link to another Gollum wiki page, use the Gollum Page Link Tag.
[[Frodo Baggins]]
The above tag will create a link to the corresponding page file named
`Frodo-Baggins.ext` where `ext` may be any of the allowed extension types. The
conversion is as follows:
1. Replace any spaces (U+0020) with dashes (U+002D)
2. Replace any slashes (U+002F) with dashes (U+002D)
If you'd like the link text to be something that doesn't map directly to the
page name, you can specify the actual page name after a pipe:
[[Frodo|Frodo Baggins]]
The above tag will link to `Frodo-Baggins.ext` using "Frodo" as the link text.
The page file may exist anywhere in the directory structure of the repository.
Gollum does a breadth first search and uses the first match that it finds.
Here are a few more examples:
[[J. R. R. Tolkien]] -> J.-R.-R.-Tolkien.ext
[[Movies / The Hobbit]] -> Movies---The-Hobbit.ext
[[モルドール]] -> モルドール.ext
## EXTERNAL LINKS
As a convenience, simple external links can be placed within brackets and they
will be linked to the given URL with the URL as the link text. For example:
[[http://example.com]]
External links must begin with either "http://" or "https://". If you need
something more flexible, you can resort to the link syntax in the page's
underlying markup format.
## ABSOLUTE VS. RELATIVE VS. EXTERNAL PATH
For Gollum tags that operate on static files (images, PDFs, etc), the paths
may be referenced as either relative, absolute, or external. Relative paths
point to a static file relative to the page file within the directory
structure of the Gollum repo (even though after conversion, all page files
appear to be top level). These paths are NOT prefixed with a slash. For
example:
gollum.pdf
docs/diagram.png
Absolute paths point to a static file relative to the Gollum repo's
root, regardless of where the page file is stored within the directory
structure. These paths ARE prefixed with a slash. For example:
/pdfs/gollum.pdf
/docs/diagram.png
External paths are full URLs. An external path must begin with either
"http://" or "https://". For example:
http://example.com/pdfs/gollum.pdf
http://example.com/images/diagram.png
All of the examples in this README use relative paths, but you may use
whatever works best in your situation.
## FILE LINKS
To link to static files that are contained in the Gollum repository you should
use the Gollum File Link Tag.
[[Gollum|gollum.pdf]]
The first part of the tag is the link text. The path to the file appears after
the pipe.
## IMAGES
To display images that are contained in the Gollum repository you should use
the Gollum Image Tag. This will display the actual image on the page.
[[gollum.png]]
In addition to the simple format, there are a variety of options that you
can specify between pipe delimiters.
To specify alt text, use the `alt=` option. Default is no alt text.
[[gollum.png|alt=Gollum and his precious wiki]]
To place the image in a frame, use the `frame` option. When combined with the
`alt=` option, the alt text will be used as a caption as well. Default is no
frame.
[[gollum.png|frame|alt=Gollum and his precious wiki]]
To specify the alignment of the image on the page, use the `align=` option.
Possible values are `left`, `center`, and `right`. Default is `left`.
[[gollum.png|align=center]]
To float an image so that text flows around it, use the `float` option. When
`float` is specified, only `left` and `right` are valid `align` options.
Default is not floating. When floating is activated but no alignment is
specified, default alignment is `left`.
[[gollum.png|float]]
To specify a max-width, use the `width=` option. Units must be specified in
either `px` or `em`.
[[gollum.png|width=400px]]
To specify a max-height, use the `height=` option. Units must be specified in
either `px` or `em`.
[[gollum.png|height=300px]]
Any of these options may be composed together by simply separating them with
pipes.
## ESCAPING GOLLUM TAGS
If you need the literal text of a wiki or static link to show up in your final
wiki page, simply preface the link with a single quote (like in LISP):
'[[Page Link]]
'[[File Link|file.pdf]]
'[[image.jpg]]
This is useful for writing about the link syntax in your wiki pages.
## SYNTAX HIGHLIGHTING
In page files you can get automatic syntax highlighting for a wide range of
languages (courtesy of [Pygments](http://pygments.org/) - must install
separately) by using the following syntax:
```ruby
def foo
puts 'bar'
end
```
The block must start with three backticks, at the beginning of a line or
indented with any number of spaces or tabs.
After that comes the name of the language that is contained by the
block. The language must be one of the `short name` lexer strings supported by
Pygments. See the [list of lexers](http://pygments.org/docs/lexers/) for valid
options.
The block contents should be indented at the same level than the opening backticks.
If the block contents are indented with an additional two spaces or one tab,
then that whitespace will be ignored (this makes the blocks easier to read in plaintext).
The block must end with three backticks indented at the same level than the opening
backticks.
## MATHEMATICAL EQUATIONS
Page files may contain mathematic equations in TeX syntax that will be nicely
typeset into the expected output. A block-style equation is delimited by `\[`
and `\]`. For example:
\[ P(E) = {n \choose k} p^k (1-p)^{ n-k} \]
Inline equations are delimited by `\(` and `\)`. These equations will appear
inline with regular text. For example:
The Pythagorean theorem is \( a^2 + b^2 = c^2 \).
## SEQUENCE DIAGRAMS
You may imbed sequence diagrams into your wiki page (rendered by
[WebSequenceDiagrams](http://www.websequencediagrams.com) by using the
following syntax:
{{{ blue-modern
alice->bob: Test
bob->alice: Test response
}}}
You can replace the string "blue-modern" with any supported style.
## API DOCUMENTATION
The Gollum API allows you to retrieve raw or formatted wiki content from a Git
repository, write new content to the repository, and collect various meta data
about the wiki as a whole.
Initialize the Gollum::Repo object:
# Require rubygems if necessary
require 'rubygems'
# Require the Gollum library
require 'gollum'
# Create a new Gollum::Wiki object by initializing it with the path to the
# Git repository.
wiki = Gollum::Wiki.new("my-gollum-repo.git")
# => <Gollum::Wiki>
By default, internal wiki links are all absolute from the root. To specify a different base path, you can specify the `:base_path` option:
wiki = Gollum::Wiki.new("my-gollum-repo.git", :base_path => "/wiki")
Get the latest version of the given human or canonical page name:
You can also run gollum with any rack-compatible server by placing this config.ru
file inside your wiki repository. This allows you to utilize any Rack middleware
like Rack::Auth, OmniAuth, etc.
#!/usr/bin/env ruby
require 'rubygems'
require 'gollum/frontend/app'
gollum_path = File.expand_path(File.dirname(__FILE__)) # CHANGE THIS TO POINT TO YOUR OWN WIKI REPO
Precious::App.set(:default_markup, :markdown) # set your favorite markup language
run Precious::App
## CONTRIBUTE
If you'd like to hack on Gollum, start by forking my repo on GitHub:
http://github.com/github/gollum
To get all of the dependencies, install the gem first. The best way to get
your changes merged back into core is as follows:
1. Clone down your fork
1. Create a thoughtfully named topic branch to contain your change
1. Hack away
1. Add tests and make sure everything still passes by running `rake`
1. If you are adding new functionality, document it in the README
1. Do not change the version number, I will do that on my end
1. If necessary, rebase your commits into logical chunks, without errors
1. Push the branch up to GitHub
1. Send a pull request to the github/gollum project.
[](https://saucelabs.com)
opts.on('--page-file-dir [PATH]', 'Specify the subdirectory for all pages. Default: repository root.',
'Example: setting this to \'pages\' will make Gollum serve only pages at \'<git-repo>/pages/*\'.') do |path|
wiki_options[:page_file_dir] = path
end
opts.on('--static', 'Use static assets. Defaults to false in development/test, defaults to true in production/staging.') do
wiki_options[:static] = true
end
opts.on('--no-static', 'Do not use static assets (even when in production/staging).') do
wiki_options[:static] = false
end
opts.on('--assets [PATH]', 'Set the path to look for static assets. Only used if --static is set to true, or environment is production/staging. Default: ./public/assets') do |path|
wiki_options[:static_assets_path] = path
end
opts.on('--css', 'Inject custom CSS into each page. The \'<wiki-root>/custom.css\' file is used (must be committed).') do
wiki_options[:css] = true
end
opts.on('--js', 'Inject custom JavaScript into each page. The \'<wiki-root>/custom.js\' file is used (must be committed).') do
wiki_options[:js] = true
end
opts.on('--no-edit', 'Disable the feature of editing pages.') do
wiki_options[:allow_editing] = false
end
opts.on('--local-time', "Use the browser's local timezone instead of the server's for displaying dates.") do
wiki_options[:show_local_time] = true
end
opts.on('--follow-renames', 'Follow pages across renames in the History view. Default: true.') do
wiki_options[:follow_renames] = true
end
opts.on('--no-follow-renames', 'Do not follow pages across renames in the History view.') do
opts.on('--critic-markup', 'Enable support for annotations using CriticMarkup.') do
wiki_options[:critic_markup] = true
end
opts.on('--irb', 'Launch Gollum in \'console mode\', with a predefined API.') do
options[:irb] = true
end
opts.on("--host [HOST]", "Hostname or IP address to listen on (default 0.0.0.0).") do |host|
options['bind'] = host
end
opts.separator ''
opts.separator ' Minor:'
opts.on("--version", "Display current version.") do
puts "Gollum " + Gollum::VERSION
opts.on('--h1-title', 'Use the first \'<h1>\' as page title.') do
wiki_options[:h1_title] = true
end
opts.on('--no-display-metadata', 'Do not render metadata tables in pages.') do
wiki_options[:display_metadata] = false
end
opts.on('--user-icons [MODE]', [:gravatar, :identicon], 'Use specific user-icons for history view.',
'Can be set to \'gravatar\' or \'identicon\'. Default: standard avatar.') do |mode|
wiki_options[:user_icons] = mode.to_s
end
opts.on('--template-dir [PATH]', 'Specify custom mustache template directory. Only overrides templates that exist in this directory.') do |path|
wiki_options[:template_dir] = path
end
opts.on('--template-page', 'Use _Template.{ext} as a template for new pages.') do
wiki_options[:template_page] = true
end
opts.on('--lenient-tag-lookup', 'Internal links resolve case-insensitively, will treat spaces as hyphens, and will match the first page found with a certain filename, anywhere in the repository. Provides compatibility with Gollum 4.x.') do
wiki_options[:case_insensitive_tag_lookup] = true
wiki_options[:global_tag_lookup] = true
wiki_options[:hyphened_tag_lookup] = true
end
opts.on('--emoji', 'Parse and interpret emoji tags (e.g. :heart:) except when the leading colon is backslashed (e.g. \\:heart:).') do
wiki_options[:emoji] = true
end
opts.separator ''
opts.separator ' Common:'
opts.on('--help', 'Display this message.') do
puts opts
exit 0
end
opts.on('--version', 'Display the current version of Gollum.') do
puts 'Gollum ' + Gollum::VERSION
exit 0
end
opts.on('--versions', 'Display the current version of Gollum and auxiliary gems.') do
require 'gollum-lib'
puts 'Gollum ' + Gollum::VERSION
puts "Running on: #{RUBY_PLATFORM} with Ruby version #{RUBY_VERSION}"
Use this tool to migrate a wiki repository created under Gollum versions 4.x or earlier to a 5.x compatibile repo.
It finds and repairs Gollum link tags that no longer work under 5.x for three reasons:
* 5.x wiki internal links may contain spaces. [[Bilbo Baggins]] and [[Bilbo-Baggins]] therefore link to distinct pages.
* 5.x wiki internal links are case senitive
* 5.x wiki internal links are no longer 'global'.
* NB: you can use the --lenient-tag-lookup option in gollum >= 5.x to enable 4.x-backwards compatible tags.
See https://github.com/gollum/gollum/wiki/5.0-release-notes#filename-handling for more information.
Usage of this script comes without any warranty.
Usage: gollum-migrate-tags /path/to/repo
NB: without the --write flag, this will be a 'dry run' that doesn't actually make any changes, but outputs the changes that would be made.
You can use the --page-file-dir and --config options as you would normally with gollum.
Requires a non-bare repository. Recommended usage:
1. Clone your wiki's repository to create a backup.
2. Run this script on your cloned repo.
3. If all looks sane, run the script with the --write option. This will overwrite files in your working directory, but not commit the changes, so you have time to review them.
4. Do a 'git diff' to inspect the changes.
5. Commit the changes if all looks sane, and push/pull them back into your original repo.
Options:
EOF
opts.on('-c', '--config [FILE]', 'Specify path to the Gollum\'s configuration file.') do |file|
options[:config] = file
end
opts.on('--page-file-dir [PATH]', 'Specify the subdirectory for all pages. Default: repository root.') do |path|
wiki_options[:page_file_dir] = path
end
opts.on('--prefer-relative-links', 'When specified, will try to replace broken links with relative links (\'[[Foo/Bar]]\' instead of \'[[/Subdir/Foo/Bar]]\') where possible.') do
migrate_options[:prefer_relative] = true
end
opts.on('--hyphenate', 'Default. Repair links that use spaces instead of hyphens: [[Bilbo Baggins]] -> [[Bilbo-Baggins]]') do
migrate_options[:hyphenate] = true
end
opts.on('--no-hyphenate', 'Turn off the --hyphenate option.') do
migrate_options[:hyphenate] = false
end
opts.on('--run-silent', 'Don\'t output anything.') do
migrate_options[:run_silent] = true
end
opts.on('--write', 'No dry run: actually perform the substitutions.') do
data:'<p>ASCIIDoc headers can be written in two ways: with differing underlines or with different indentation using <code>=</code> (equals sign). ASCIIDoc supports headings 1-4. The editor will automatically use the <code>=</code> notation. To create a level one header, prefix your line with one <code>=</code>. Level two headers are created with <code>==</code> and so on.</p>'
},
{
menuName:'Bold / Italic',
data:'<p>To display text as <strong>bold</strong>, wrap the text in <code>*</code> (asterisks). To display text as <em>italic</em>, wrap the text in <code>_</code> (underscores). To create <code>monospace</code> text, wrap the text in <code>+</code> (plus signs).'
},
{
menuName:'Scripts',
data:'<p>Superscript and subscript is created the same way as other inline formats. To create superscript text, wrap your text in <code>^</code> (carats). To create subscript text, wrap your text in <code>~</code> (tildes).</p>'
data:'<p>ASCIIDoc allows paragraphs to have optional titles or icons to denote special sections. To make a normal paragraph, simply add a line between blocks and a new paragraph will start. If you want to title your paragraphs, adda line prefixed by <code>.</code> (full stop). An example paragraph with optional title is displayed below:<br><br><code>.Optional Title<br><br>This is my paragraph. It is two sentences long.</code></p>'
},
{
menuName:'Source Blocks',
data:'<p>To create source blocks (long blocks of code), follow the same syntax as above but with an extra line denoting the inline source and lines of four dashes (<code>----</code>) delimiting the source block.. An example of Python source is below:<br><br><code>.python.py<br>[source,python]<br>----<br># i just wrote a comment in python<br># and maybe one more<br>----</code></p>'
},
{
menuName:'Comment Blocks',
data:'<p>Comment blocks are useful if you want to keep notes for yourself inline but do not want them displayed to the public. To create a comment block, simply wrap the paragraph in dividers with four slashes (<code>////</code>). An example comment block is below:<br><br><code>////<br>My comment block is here now<br><br>It can be multiple paragraphs. Really.<br>////</p>'
},
{
menuName:'Quote Blocks',
data:'<p>Quote blocks work much like comment blocks — simply create dividers using four underscores (<code>____</code>) around your quote. An example quote block is displayed below:<br><code>____<br>This is my quote block. Quote something nice here, otherwise there is no point in quoting.<br>____</code></p>'
}
]
},
{
menuName:'Macros',
content:[
{
menuName:'Links',
data:'<p>To create links to external pages, you can simply write the URI if you want the URI to link to itself. (i.e., <code>http://github.com/</code> will automatically be parsed to <a href="javascript:void(0);">http://github.com/</a>. If you want different text to be displayed, simply append it to the end of the URI in between <code>[</code> (brackets.) For example, <code>http://github.com/[GitHub]</code> will be parsed as <a href="javascript:void(0);">GitHub</a>, with the URI pointing to <code>http://github.com</code>.</p>'
},
{
menuName:'Images',
data:'<p>Images in ASCIIDoc work much like hyperlinks, but image URLs are prefixed with <code>image:</code>. For example, to link to an image at <code>images/icons/home.png</code>, write <code>image:images/icons/home.png</code>. Alt text can be added by appending the text to the URI in <code>[</code> (brackets).</p>'
(function(b,d){vari="2.7.5";vara="http://www.stixfonts.org/";varf="https://github.com/mathjax/MathJax/tree/master/fonts/HTML-CSS/TeX/otf";varh=b.CombineConfig("FontWarnings",{messageStyle:{position:"fixed",bottom:"4em",left:"3em",width:"40em",border:"3px solid #880000","background-color":"#E0E0E0",color:"black",padding:"1em","font-size":"small","white-space":"normal","border-radius":".75em","-webkit-border-radius":".75em","-moz-border-radius":".75em","-khtml-border-radius":".75em","box-shadow":"4px 4px 10px #AAAAAA","-webkit-box-shadow":"4px 4px 10px #AAAAAA","-moz-box-shadow":"4px 4px 10px #AAAAAA","-khtml-box-shadow":"4px 4px 10px #AAAAAA",filter:"progid:DXImageTransform.Microsoft.dropshadow(OffX=3, OffY=3, Color='gray', Positive='true')"},Message:{webFont:[["closeBox"],["webFont","MathJax is using web-based fonts to display the mathematics on this page. These take time to download, so the page would render faster if you installed math fonts directly in your system's font folder."],["fonts"]],imageFonts:[["closeBox"],["imageFonts","MathJax is using its image fonts rather than local or web-based fonts. This will render slower than usual, and the mathematics may not print at the full resolution of your printer."],["fonts"],["webFonts"]],noFonts:[["closeBox"],["noFonts","MathJax is unable to locate a font to use to display its mathematics, and image fonts are not available, so it is falling back on generic unicode characters in hopes that your browser will be able to display them. Some characters may not show up properly, or possibly not at all."],["fonts"],["webFonts"]]},HTML:{closeBox:[["div",{style:{position:"absolute",overflow:"hidden",top:".1em",right:".1em",border:"1px outset",width:"1em",height:"1em","text-align":"center",cursor:"pointer","background-color":"#EEEEEE",color:"#606060","border-radius":".5em","-webkit-border-radius":".5em","-moz-border-radius":".5em","-khtml-border-radius":".5em"},onclick:function(){if(c.div&&c.fade===0){if(c.timer){clearTimeout(c.timer)}c.div.style.display="none"}}},[["span",{style:{position:"relative",bottom:".2em"}},["x"]]]]],webFonts:[["p"],["webFonts","Most modern browsers allow for fonts to be downloaded over the web. Updating to a more recent version of your browser (or changing browsers) could improve the quality of the mathematics on this page."]],fonts:[["p"],["fonts","MathJax can use either the [STIX fonts](%1) or the [MathJax TeX fonts](%2). Download and install one of those fonts to improve your MathJax experience.",a,f]],STIXfonts:[["p"],["STIXPage","This page is designed to use the [STIX fonts](%1). Download and install those fonts to improve your MathJax experience.",a]],TeXfonts:[["p"],["TeXPage","This page is designed to use the [MathJax TeX fonts](%1). Download and install those fonts to improve your MathJax experience.",f]]},removeAfter:12*1000,fadeoutSteps:10,fadeoutTime:1.5*1000});if(MathJax.Hub.Browser.isIE9&&document.documentMode>=9){deleteh.messageStyle.filter}varc={div:null,fade:0};vare=function(m){if(c.div){return}varj=MathJax.OutputJax["HTML-CSS"],n=document.body;if(b.Browser.isMSIE){if(h.messageStyle.position==="fixed"){MathJax.Message.Init();n=document.getElementById("MathJax_MSIE_Frame")||n;if(n!==document.body){h.messageStyle.position="absolute"}}}else{deleteh.messageStyle.filter}h.messageStyle.maxWidth=(document.body.clientWidth-75)+"px";vark=0;while(k<m.length){if(MathJax.Object.isArray(m[k])){if(m[k].length===1&&h.HTML[m[k][0]]){m.splice.apply(m,[k,1].concat(h.HTML[m[k][0]]))}else{if(typeofm[k][1]==="string"){varl=MathJax.Localization.lookupPhrase(["FontWarnings",m[k][0]],m[k][1]);l=MathJax.Localization.processMarkdown(l,m[k].slice(2),"FontWarnings");m.splice.apply(m,[k,1].concat(l));k+=l.length}else{k++}}}else{k++}}c.div=j.addElement(n,"div",{id:"MathJax_FontWarning",style:h.messageStyle},m);MathJax.Localization.setCSS(c.div);if(h.removeAfter){b.Register.StartupHook("End",function(){c.timer=setTimeout(g,h.removeAfter)})}d.Cookie.Set("fontWarn",{warned:true})};varg=function(){c.fade++;if(c.timer){deletec.timer}if(c.fade<h.fadeoutSteps){varj=1-c.fade/h.fadeoutSteps;c.div.style.opacity=j;c.div.style.filter="alpha(opacity="+Math.floor(100*j)+")";setTimeout(g,h.fadeoutTime/h.fadeoutSteps)}else{c.div.style.display="none"}};if(!d.Cookie.Get("fontWarn").warned){b.Startup.signal.Interest(function(m){if(m.match(/HTML-CSS Jax - /)&&!c.div){varj=MathJax.OutputJax["HTML-CSS"],n=j.config.availableFonts,l;vark=(n&&n.length);if(!k){h.HTML.fonts=[""]}else{if(n.length===1){h.HTML.fonts=h.HTML[n[0]+"fonts"]}}if(j.allowWebFonts){h.HTML.webfonts=[""]}if(m.match(/- Web-Font/)){if(k){l="webFont"}}else{if(m.match(/- using image fonts/)){l="imageFonts"}else{if(m.match(/- no valid font/)){l="noFonts"}}}if(l&&h.Message[l]){MathJax.Localization.loadDomain("FontWarnings",[e,h.Message[l]])}}})}})(MathJax.Hub,MathJax.HTML);MathJax.Ajax.loadComplete("[MathJax]/extensions/FontWarnings.js");
File diff suppressed because one or more lines are too long
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.