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.
Avoids rendering HTML-ized CSS and/or Javascript by removing the
contents of script and style elements as well as the elements
themselves.
/cc @technoweenie
Pull Request: master
Now Gollum does all its Markdown processing through GitHub::Markup; if
you require a custom Markdown renderer using Redcarpet or another
library, you can hot-load it from your own code base:
Gollum::Wiki.markup_classes[:markdown] = YourRedcarpetRenderer
With these changes, the Markdown rendered in Gollum wikis will have the
same quality and safety as the MD we render everywhere else @ GitHub.
This commit also changes the old `markup_class` accessor to
`markup_classes`, allowing users to specify a custom Markup class for
each markup language.
Commit df505a7289 removed ruby1.8.rb but it was still included in the gemspec which caused Bundler to complain about an invalid Gemspec.
*NOTE* There are five test failures when running 'rake'. I checked out the last commit before Tom's change (d3594f6652) and that also has these five failures so I'm happy that we didn't introduce them.
**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 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`
# 1.4.0 / 2012-04-10
* Minor
* Add a way to configure the `#id_prefix` property of Sanitization
objects.
* Add web sequence diagrams support
* Support for updating wysiwyg components when markup language changes
* Support RedCarpet 2.0
* Allow ftp and irc links in wiki markup
* Minor ui fixups
* Bug Fixes
* Include the language of the code snippet when making a uniquely
identifiable sha of a code snippet while rendering a page.
* Pygments lexer forces utf8 encoding
* Remove MathJax, this created problems in production for us.
We'll look at bringing it back in future releases
# 1.3.1 / 2011-07-21
* Major Enhancements
* Allow prefixed ID attributes in headers to support internal linking
(#146).
* Markdown pages are rendered through Redcarpet by default (#176).
* Minor Enhancements
* Remove Edit button on Preview pages (#164).
* Simplify Wiki#inspect and Page#inspect.
* Bug Fixes
* Fixed broken preview functionality (#157).
* Fixed sidebar/footer rendering problems related to whitespace (#145).
# 1.3.0 / 2011-04-25
* Major Enhancements
* Listing of all Pages
* Support for running Gollum under a separate branch.
* Minor Enhancements
* Fix a security issue with rendering Mathjax.
# 1.2.0 / 2011-03-11
* Major Enhancements
* Major HTML/CSS/JS overhaul.
* Add Sidebars (similar to Footers).
* Add commit reverts.
* Minor Enhancements
* Optimization in source code highlighting, resulting in a huge
decrease in rendering time.
* Security fixes related to source code highlighting.
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.
**Gollum version 5.0 is out!** See [here](https://github.com/gollum/gollum/wiki/5.0-release-notes) for a list of changes and new features compared to Gollum version 4.x, and see some [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:
* A Gollum repository's contents are human-editable text or markup 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 system editor or IDE (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 with GitHub wikis (see `--lenient-tag-lookup`)
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:
* 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 [adapter](https://github.com/gollum/rugged_adapter) for [rugged](https://github.com/libgit2/rugged) by default. 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:
1. Ruby is best installed either via [RVM](https://rvm.io/) or a package manager of choice.
2. Gollum is best installed via RubyGems:
```
[sudo] gem install gollum
```
Installation examples for individual systems can be seen [here](https://github.com/gollum/gollum/wiki/Installation).
$ [sudo] gem install gollum
To run, simply:
If you're installing from source, you can use [Bundler][bundler] to pick up all the
* [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.
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)):
* [Pod](http://perldoc.perl.org/perlpod.html) -- requires Perl >= 5.10 (the `perl` command must be available on your command line)
* Lower versions should install `Pod::Simple` from CPAN.
* [ReStructuredText](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html) -- requires python >= 2 (the `python2` command must be available on your command line)
* Note that Gollum will also need you to install `docutils` for your Python 2.
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:
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.
$ gollum
See [here](https://github.com/gollum/gollum/wiki/Custom-rendering-gems) for instructions on how to use custom rendering gems and set custom options.
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:
## RUNNING FROM SOURCE
$ gollum --help
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.
### Rack
## REPO STRUCTURE
Gollum can also be ran 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).
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.
### Rack, with an authentication server
Gollum can also be ran 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).
## PAGE FILES
### Docker
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:
Gollum can also be ran via [Docker](https://www.docker.com/). More on that [over here](https://github.com/gollum/gollum/wiki/Gollum-via-Docker).
| --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. |
| --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-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. |
## SIDEBAR FILES
**Notes:**
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.
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.
## FOOTER FILES
### Config file
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.
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.
**All of the mentioned alterations work both for Gollum's config file (`config.rb`) and Rack's config file (`config.ru`).**
## HTML SANITIZATION
## CONTRIBUTING
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 (as the first characters on the
line). 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.
If the block contents are indented 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 as the first characters on a
line.
## 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 theorum is \( a^2 + b^2 = c^2 \).
Gollum uses [MathJax](http://www.mathjax.org/) to convert the TeX syntax into
output suitable for display in web browsers.
## 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:
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('--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.') 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
* you may not use this file except in compliance with the License.
*
* http://www.apache.org/licenses/LICENSE-2.0
*/
MathJax.Unpack([
['(function(c){var i="1.0";var g=','MathJax.Hub','.Insert({prefer:{MSIE:"MML",Firefox:"MML",Opera:"HTML",other:"HTML"}},(',1,'.config.MMLorHTML||{}));var e={Firefox:3,Opera:9.52,MSIE:6,Chrome:0.3,Safari:2,Konqueror:4};var h=(c','.Browser','.version==="0.0"||','c.Browser.versionAtLeast','(e[c',5,']||0));var b;try{new ActiveXObject("MathPlayer.Factory.1");b=true}catch(d){b=false}var f=(c',5,'.isFirefox&&',7,'("1.5"))||(c',5,'.isMSIE&&b)||(c',5,'.isOpera&&',7,'("9.52"));var a=(g.prefer&&typeof(g.prefer)==="object"?g.prefer[',1,5,']||g.prefer.other||"HTML":g.prefer);if(h||f){if(f&&(a==="MML"||!h)){','c.config.jax.unshift("output/','NativeMML")}else{',24,'HTML-CSS")}}else{c.PreProcess','.disabled=true;','c.prepareScripts',28,'MathJax.Message.Set("Your browser does not support MathJax",null,4000);c.Startup.signal.Post("MathJax not supported")}})(',1,');MathJax.Ajax.loadComplete("[MathJax]/config/MMLorHTML.js");']
<spanid="id1"></span><h1>CSS Style Objects<aclass="headerlink"href="#css-style-objects"title="Permalink to this headline">¶</a></h1>
<p>Many MathJax components allow you to specify CSS styles that control
the look of the elements they create. These are described using CSS
style objects, which are JavaScript objects that represent standard
CSS declarations. The main CSS style object is a collection of
<cite>name:value</cite> pairs where the <cite>name</cite> is the CSS selector that is being
defined, and the <cite>value</cite> is an object that gives the style for that
selector. Most often, the selector will need to be enclosed in
quotation marks, as it will contain special characters, so you would
need to use <ttclass="docutils literal"><spanclass="pre">"#myID"</span></tt> rather than just <ttclass="docutils literal"><spanclass="pre">#myID</span></tt> and <ttclass="docutils literal"><spanclass="pre">"ul</span><spanclass="pre">li"</span></tt>
rather than just <ttclass="docutils literal"><spanclass="pre">ul</span><spanclass="pre">li</span></tt>.</p>
<p>The value used to define the CSS style can either be a string
containing the CSS definition, or a javascript object that is itself a
collection of <cite>name:value</cite> pairs, where the <cite>name</cite> is the attribute
being defined and <cite>value</cite> is the value that attibute should be given.
Note that, since this is a JavaScript object, the pairs are separated
by commas (not semi-colons) and the values are enclosed in quotation
marks. If the name contains dashes, it should be enclosed in
quotation marks as well.</p>
<p>For example, <ttclass="docutils literal"><spanclass="pre">jax/output/HTML-CSS/config.js</span></tt> includes the following
<p>This defines two CSS styles, one for the selector <ttclass="docutils literal"><spanclass="pre">.MathJax</span>
<spanclass="pre">.merror</span></tt>, which specifies a background color, foreground color,
border, and so on, and a second for <ttclass="docutils literal"><spanclass="pre">.MathJax_Preview</span></tt> that sets its
color.</p>
<p>You can add as many such definitions to a <ttclass="docutils literal"><spanclass="pre">styles</span></tt> object as you
wish. Note, however, that since this is a JavaScript object, the
selectors must be unique (e.g., you can’t use two definitions for
<ttclass="docutils literal"><spanclass="pre">"img"</span></tt>, for example, as only the last one would be saved). If you
need to use more than one entry for a single selector, you can add
comments like <ttclass="docutils literal"><spanclass="pre">/*</span><spanclass="pre">1</span><spanclass="pre">*/</span></tt> and <ttclass="docutils literal"><spanclass="pre">/*</span><spanclass="pre">2</span><spanclass="pre">*/</span></tt> to the selector to make them
unique.</p>
<p>It is possible to include selectors like <ttclass="docutils literal"><spanclass="pre">"@media</span><spanclass="pre">print"</span></tt>, in which
case the value is a CSS style object. For example:</p>
<p>The various extensions and output processors include more examples of
CSS style objects, so see the code for those files for additional
samples. In particular, the <ttclass="docutils literal"><spanclass="pre">extensions/MathMenu.js</span></tt>,
<ttclass="docutils literal"><spanclass="pre">extensions/MathZoom.js</span></tt>, <ttclass="docutils literal"><spanclass="pre">extensions/FontWarnsing.js</span></tt>, and
<ttclass="docutils literal"><spanclass="pre">jax/output/HTML-CSS/jax.js</span></tt> files include such definitions.</p>
</div>
</div>
</div>
</div>
<divclass="sphinxsidebar">
<divclass="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<pclass="topless"><ahref="HTML-snippets.html"
title="previous chapter">Describing HTML snippets</a></p>
<spanid="html-snippets"></span><h1>Describing HTML snippets<aclass="headerlink"href="#describing-html-snippets"title="Permalink to this headline">¶</a></h1>
<p>A number of MathJax configuration options allow you to specify an HTML
snippet using a JavaScript object. This lets you include HTML in your
configutation files even though they are not HTML files themselves.
The format is fairly simple, but flexible enough to let you represent
complicated HTML trees.</p>
<p>An HTML snippet is an array consisting of a series elements that formt
he HTML tree. Those elements are one of two things: either a string,
which represents text to be included in the snippet, or an array,
which represents an HTML tag to be included. In the latter case, the
array consists of three items: a string that is the tag name (e.g.,
“img”), an optional object that gives attributes for the tag (as
described below), and an optional HTML snippet array that gives the
contents of the tag.</p>
<p>When attributes are provided, they are given as <cite>name:value</cite> pairs,
with the <cite>name</cite> giving the attribute name, and <cite>value</cite> giving its
<p>represents an HTML snippet that includes one element: an <ttclass="docutils literal"><spanclass="pre"><img></span></tt> tag
with <ttclass="docutils literal"><spanclass="pre">src</span></tt> set to <ttclass="docutils literal"><spanclass="pre">/images/mypic.jpg</span></tt>. That is, this is
<spanclass="s2">" carefully before proceeding"</span>
<spanclass="p">]</span>
</pre></div>
</div>
<p>which is equivalent to</p>
<divclass="highlight-html"><divclass="highlight"><pre>please read the <spanclass="nt"><a</span><spanclass="na">href=</span><spanclass="s">"instructions.html"</span><spanclass="nt">></span>instructions<spanclass="nt"></a></span> carefully
before proceeding.
</pre></div>
</div>
<p>A final example shows how to set style attributes on an object:</p>
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.