Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Beta release notes
About this version
This is a pre-release beta version of the Annotum WordPress theme. It contains bugs and should not be used for a production system. Please refer to the known issues list for known bugs and open development tasks. Please see other important caveats in the Annotum license/
Annotum is free (speech and beer).
Important: Annotum is best suited for use on a new, or separate, WordPress installation. It is not recommended to install WordPress on to an existing blog or other WordPress site.
If you host your own Annotum-powered site using WordPress, the following are the minimum requirements necessary:
- WordPress version 3.3
- PHP 5.2.4 (including libxml 2.6.29 or higher)
Basic Install (existing WordPress site).
The simplest installation method is to install the Annotum theme in an existing WordPress setup (for example if your hosting provider offers a one-click WordPress setup). To do that
- Download the beta distribution package to your computer, and extract the two theme files
current.zip(i.e., extract these zip files from the distribution package).
- Log into your WordPress admin dashboard, and navigate to Appearance > Themes > Install Theme > Upload.
- Find the
current.zipfiles from step 1, and use the form to upload them to your site. You can activate either Annotum-base or Current, but you must install Annotum-base to use Annotum. See "Theme Setup" below for next steps.
Stand alone installation options
In addition to being offered as a standard
zip file, we offer complete, stand-alone packages that contain all components needed to set up a working Annotum setup. Packages are offered for both Mac/OSx and for Windows. Please refer to Annotum stand alone installers for more information.
Once you've installed and activated the theme, log in as an administrator and navigate to the Themes dashboard (Dashboard > Appearance > Themes). From there, click
Annotum Settings, and select the desired options:
Enable Workflow: This enables the Annotum workflow features. IMPORTANT: enable this or you won't get any of the workflow features.
Enable workflow notifications: sends an email to appropriate authors/editors/reviewers whenever workflow actions are taken.
Note: workflow notifications generate an email message to every site admin and editor for every workflow action in addition to role-specific (author, co-author) notifications. This can generate quite a bit of email on an active site!
Note: Notifications will not work unless your WordPress setup is configured to send mail. For local installations using Annotum2Go, AnnotumMAMP, or other stand-alone LAMP stacks, you must run a local mail server such as MercuryMail or install a WordPress plugin such as wp-mail-smtp.
Figure: Annotum email notification matrix
Add credentials for CrossRef DOI lookups. Get credentials (i.e., register your email) here, and then add them to the Annotum Settings screen [no password needed].
Allow article authors to see reviewers: This enables an "open-process" review style in which article authors can see all reviewers and their review comments. You may wish to leave this deselected for a more traditional anonymous review process.
Getting started with Annotum
To dive into creating articles with Annotum, follow these steps:
- Log into Annotum at http://YOUR_SITE_URL/PATH/wp-login.php
- From the top admin bar, navigate to Add New > Article.
- Enter a Title (required) and a Subtitle, Abstract, or other information if you wish.
- The main action in Annotum takes place in the article editor, a WYSIWYAATD (What-you-see-is-what-you-are-allowed-to-do) editing control with many features such as tables, images, and equations. The editor shows you where you are in the structure of the document, whether in the
titleof a section, a
paragraphor in one of the elements of a
- Typing/editing tips:
enterto create a new paragraph, and
ctrl+enterto create a new section
- Use the
full screenview to enlarge the editor to take up the whole window. But don't forget to save from time to time!
- Typing/editing tips:
- Enter some text, click save, and then preview your article.
- Now experiment with inserting images, tables, and equations.
- When you're done editing, click
submit for review(if you have enabled workflow. If not, you can click
publish.) You can now select or invite reviewers, or if you are an admin or editor simply click
- Finally, view the published article, and download a copy in XML format. (Annotum uses the kipling dtd, a subset of the NLM's Journal Article DTD 3.0.
- Annotum supports round-tripping of XML content. You can export your articles in Kipling-XML format, then easily upload them on any other Annotum site.
- Hooray! you've just created and published your first article with Annotum.
For more specifics, please refer to the detailed Feature Walkthrough.
Additional Theme Setup
Annotum uses standard WordPress features such as widgets and menus for customization. There are also some Theme Settings such as callouts.
Annotum2go and AnnotumMAMP each provide a basic widget setup.
Note: the initial theme content is quite sparse by design. You will almost certainly want to add menus and sidebar widgets to enhance the layout of your site.
Annotum's workflow is based around the
Articles custom post type and a few custom user permission levels: Author, Reviewer, Editor, and Admin.
Annotum and WordPress Roles
Adminaka publication staff. Admins can perform all functions and see all comments. They can add and remove reviewers and coauthors, change authors, approve/reject/request revisions on articles, and publish approved articles. Create admins by granting them the "Admin" WordPress user level.
Editor. Editors can do everything except publish articles (move from
published). Create Editors by granting them the "Editor" WordPress user level.
Author. Authors can create articles, add and remove coauthors, and submit articles for review. Authors cannot see review comments on their articles, nor do they see who the reviewers are. Authors can be added with either the "Contributor" or "Author" WordPress user level. If "Author" is used, the user will be able to create regular posts and pages via the built-in WordPress functions. Note that Co-authors are defined at the article level (not user level) when they are added by the article author. They can be any level from Contributor on up.
Reviewer. Reviewers can submit review comments and view replies to their own review comments only. Reviewers are defined at the article level when they are added by the editor. They can be any level from Contributor on up.
Subscriber. Essentially a site viewer, they can make comments on published articles.
Please see Annotum permissions for more information.
Create a new article via the "new article" button from the "Articles" dashboard. You'll see various sections for adding co-authors, including sections of your article, etc. NOte that future versions will have a greatly-enhanced set of authoring controls including the ability to import and export XML, structured equation/figure/table support, and other features such as robust handling of references. IN the preview-beta version only some features are available.
NEW! References: easily add references using PubMedIDs and CrossRef DOIs. Click the
NEW! Enhanced XML export: nearly complete NLM-compliant XML output.
NEW! Improved image and table handling
Once you've created an article, you can:
- Preview the article
- Add Co-authors (once you do, they can also edit the article)
- Submit the article for review
The basic workflow is:
- The Author creates a new article, and optionally invites co-authors to work on it. All co-authors can post internal comments on the article during this process.
- When ready, the Author submits the article for review via the
Submit for Reviewbutton on the article editing screen.
- The editor assigns reviewers, each of whom can enter review comments and a recommendation: Approve, Reject, or Request Revisions. The editor may reply to review comments; reviewers can only see their own comments and replies to them.
- When the reviews are in, the editor can Approve or Reject the article or Request Revisions. Only Approved articles can be published.
- Once an article is approved, an admin (think of admins as the publication staff) can publish it to the site.
Please visit http://annotum.wordpress.com for the latest news, downloads, and other support information. Or submit bug reports or questions via the Annotum issues list at https://github.com/Annotum/Annotum/issues
Follow @annotum on Twitter for updates.
Rights for products and code contained herein are owned by their respective copyright holders or available via the referenced license (GPL, etc).
All components in this package are believed to be open source and freely-redistributable.
Annotum is free (as in beer and speech).