Skip to content
Browse files

Added docs folder from

  • Loading branch information...
Chris S
Chris S committed Dec 27, 2018
1 parent d641adf commit 271cdc6f72382a29caef16d9194c83828238d49c
@@ -0,0 +1,17 @@
# Azure website deployments
If you have a Microsoft Azure account, you can deploy a new Roadkill wiki site very quickly using the website deployment option.

## Pre-requisites
- You'll need a Githubaccount before you can use the deployment option in Azure.
- You'll need to fork Roadkill on either Github or Bitbucket. You can do this via the website. You should fork the "v2.0" branch for stability, or "master" if you prefer the bleeding edge.

## Deployment steps:
1. Create a new website
2. Go to the "configure" page in the top menu
3. Navigate to the "app settings" section
4. Login using your Github details
5. Choose Roadkill from your list of repositories.
6. You will need to FTP (username/password is in the publish settings file) and download the roadkill.config file. Change the "installed=true" to "installed=false" in this file.
This setting is true by default to avoid automatic deployments from showing their installer screen when a new commit is made to Roadkill.

You will need to create a SQL or mySQL database in Azure too, copying the connection string details.
@@ -0,0 +1,10 @@
# Common issues

## Unable to load DLL 'SQLite.Interop.dll': The specified module could not be found. (Exception from HRESULT: 0x8007007E)

Copy this DLL from app_data folder to the bin folder.

## Search doesn't return the latest pages
Occasionally the Lucene index gets out of sync with the site from an error or other reason. This can also happen when a page is deleted - the whole index is updated when a page is created or deleted. If this happens you should login as the administrator for the site and head to Site settings->Tools and use the "Rebuild search index" option.

This is the best thing to do for any search related problems, as it 99% of the time it will resolve the issue you're having.
@@ -0,0 +1,40 @@
# Configuration
Roadkill is configured using a combination of settings stored in the Roadkill.config file and in the database. The database connection string is stored in the connectionString.config file, and along with the Roadkill.config file is reference inside the web.config file.

## Roadkill.config
This file contains all application settings for Roadkill that typically need an application restart, or are not just cosmetic preferences. The installer will configure the file for you when you run the install wizard, if you need to change the config file later each of the properties available in the `<roadkill...` section can be found in the Api Documentation

## connectionStrings.config
Your database connection string should be stored in the connectionStrings.config file in the website root. By default, this will be empty.

There is usually no reason to change the name of the connectionString in this section as it ties in with the connectionName setting inside the roadkill section.

## Changing the language of the site
If you want to force the language of your site to something other than the one installed on the server, you can do this using the `<globalization>` tag inside the `<system.web>` section.

This element is included in the Roadkill web.config, the example below shows how to force the site to use Spanish (Spain), a full list of valid locale names can be found on MSDN.

`<globalization uiCulture="es-ES" culture="es-ES" />`
The localization of the various labels on the site is based off this setting, and is configured during the installation.

## Caching
Roadkill uses basic object caching for its caching strategy, along side browser caching. This saves trips to the database and is important for text content for mid-to-high traffic websites and responsiveness. By default Roadkill uses the .NET System.Runtime.Caching's default cache, which is similar to ASP.NET's cache for its object cache. This doesn't scale across web servers, so should be turned off if you are using multiple servers.

If you wish to scale to more than one server please contact us via Bitbucket, and a new version can be released fairly quickly to support scalable caches such as Appfabric or Couchbase. The object cache is based off the plugable System.Runtime.Caching architecture making this a simple change to make.

## Email server settings
If you have setup the Roadkill installation to allow signups from users, you will want to setup a mail server that the signup and lost emails are sent via. This can be done via the section which is included in the Roadkill web.config by default, but is configured so that all emails are written as files to a drop folder. Below are the default settings, full details can be found on MSDN -

<!-- Change these settings for signup and lost password emails -->
<smtp deliveryMethod="SpecifiedPickupDirectory" from="">
<specifiedPickupDirectory pickupDirectoryLocation="C:\inetpub\temp\smtp" />

## Settings that are stored in the database
The settings available through the 'Site Settings' menus (admins only) reflects all the settings that are stored in the database. These are stored as JSON in the database, so can be easily edited if needed. The full list of settings are available in the API documentation
@@ -0,0 +1,32 @@
# Creating and editing pages

## Creating a new page
To create a page in Roadkill, you need to have an editor or administrator login - you cannot edit or create pages anonymously. There are various ways of setting up user rights on your site, which can be found on Users and permissions page.

To create a page, click on the "New page" link on the navigation bar (left side for the media wiki theme). You will then need fill the title for the page and some text content. The format of the text is dictated by the markup type for the site, by default this will be Creole wiki markup which is a more consistent form of the media wiki markup you find on sites such as wikipedia.

The editor is not WYSIWYG, but will insert the tokens/markup for bold, italic, underline, headings, lists, links and images. The question mark button gives you help for the accepted special tokens for the current markup type.

If you are an administrator, you have the option of locking down the page via the "This page can only be edited by administrators." checkbox. This will ensure editor logins cannot edit the page, or revert it to previous versions. This is useful for important pages on your site, such the homepage.

You can embed images into your page using the image button, which launches a file explorer in a new dialog allowing you upload images. By default, Roadkill strips all dangerous HTML from the text which includes script tags, style tags, iframe tags.

You can preview your changes before saving, which displays your page inside a new dialog using the same display engine as the Roadkill site. Once you're happy with this, you can save the page.

Roadkill allows you to categorize your pages using the tags textbox. You can enter relevant tags (which will auto complete if the tag already exists) for the page - more on this below.

## Editing a page
Editor logins and administrators can edit any page in the system, changing the title, tags and text content. This is works the same way (and uses the same interface) as creating a new page.

## Page version history and reverting
Every page edit is stored as a new version in Roadkill, which allows you to revert back to previous versions of the page. This can be done via the "View history" link that is available on every page.

The history page shows every version of the page, clicking on a particular version will show the differences between that version and a previous version. Green highlighted text indicates new additions to the page, red highlighted text shows deletions to the page. From the main history page you are able to move back to a previous version via the "revert" link, this will however create a new version of the page itself.

## Tags (aka categories)
Roadkill differs slightly from other wiki engines in that it approaches categorizing pages from a blog engine perspective, by using tags rather than categories. Obviously the difference can be seen as just semantics, but tagging allows you use as many tags as you like for each page, giving a page multiple categories. These tags are also searchable in the Roadkill search interface, more on this on [Searching with the inbuilt search engine] page.

There is one special tag built into Roadkill which is the "homepage" tag. This can be used on one page only (the first page is always used), and tells Roadkill that this page should be used for the homepage on the site.

## Unsafe HTML
By default Roadkill will remove any HTML tags and attributes that aren't inside the ~/App_Data/Internal/htmlwhitelist.xml file. Any javascript, scripts, css behaviours are removed from the page output, and all attributes are also HTML encoded. More information on how the HTML sanitization works can be found in [this blog post](
@@ -0,0 +1,4 @@
# Custom markup tokens
You can add your own markup tokens that are replaced by editing the `~/App_Data/customvariables.xml` file. This file uses regular expressions to search and replace tokens for example `(youtube:someid)` is replaced with the HTML to display a youtube video.

You will need to restart the application by making a web.config change for any new tokens to show.
@@ -0,0 +1,32 @@
# Images and media
Roadkill allows you to upload images and other files which you can reference in your pages, or in the case of images, show on the page.

To upload files, navigate to the "Manage Files" link in the menu. For editors, this will allow you to create folders and upload files. Admin users can additionally delete files, and folders if they are empty.

## Restricting file extensions
Admins can restrict the type of files that can be uploaded in the Site Settings page by specifying the file extensions that can be uploaded, in comma separated format.

## Maximum file size
This is set to 50mb by default. If you need to increase or decrease this amount, you should edit the web.config file and look for "50mb" - you will need to change the setting in two places, one is in Kb another is in bytes.

If the file size exceeds the limit no error message is shown on the page.

## Setting up mime types for custom extensions
By default Roadkill serves files using the mime-type that is configured in IIS. If access to IIS is not available, a static list of mime types is used (the full list can be [found here](

If you need to add a file extension that doesn't have a mime type setup in IIS (for example, a .sql file), you can either set this up in IIS or inside the Roadkill web.config. An example of doing this is in the web.config file but commented out.

## Adding an image to the page
You can reference existing images by clicking on the image button, finding the image you want to show on the page and clicking the bottom right "select" button. This will display a small preview of the image first.

When you add an image, the markup will automatically be added to the editor text box for your page. You will probably need to tweak this for your needs, for details on the markup see the help for each markup type via the question mark button

## Linking to uploaded files
You can link to uploaded files by using "attachment:" or "~/" followed by the full path to the file inside the link tag. This should include a slash at the start. For example in the Creole markup:

`This is my Excel file: [[attachment:/Spreadsheets/Sheet1.xls|excel file]] and this is my [[~/Word/doc.docx|Word document]]`

## Atttachments folder
Files are uploaded to the folder you set in the installer, which you can also change as an admin under Site settings->configuration. This defaults to ~/App_Data/Attachments.

The folder can be a file share if needed, however the folder should have read and write access to the same user that the application pool for the site is running under.
@@ -0,0 +1,16 @@
# Importing and Exporting

## Importing
Roadkill currently has one option for importing existing content, which is from a Screwturn 2/3 installation. Future versions of Roadkill will include a REST API for importing data, but for now this is the only import option.

To import from a Screwturn database, you need to login as an administrator and head to the site settings->tools page. From here, enter your Screwturn database connection string (non-database installations aren't supported) and the tool will import the content including page history and categories into your Roadkill instance.

## Exporting
Roadkill supports 4 types of exporting:

- Exporting all content as a SQL file
- Exporting pages and content as an XML file
- Exporting all image/media uploads
- Exporting each page as text (.wiki) file.

You need to login as an administrator and head to the site settings->tools page to export. The last three export types will supply you with the content in .zip format, the .wiki text file export will include the page tags at the top of the file and then the content itself.
@@ -0,0 +1,33 @@
# Installing

## Pre-requisites
Roadkill requires IIS 7+ (although it will work with IIS Express and Cassini).

You will some basic technical knowledge of Windows to setup IIS, in particular enabling ISAPI handlers and permissions.

You do not need a database server - you can use SQLite if you choose. SQL Server Compact (SQL Server CE) is also supported.

Roadkill also has limited support for Mono on Ubuntu - see the Mono installation page for more details.

## Installing
Download the current version (which is a ZIP file) and unzip it to a new folder. If you are a developer planning to use Roadkill on your own machine or remote access to another machine, you will need to create an IIS site before installing - Roadkill does not do this for you in the wizard.

There is a howto for this on this Microsoft page:

Once your site is created and the file is unzipped, copy/FTP the unzipped Roadkill files to your website root folder. Now open your site in your browser, for example: http://localhost/roadkill/

Roadkill has been designed to work from any virtual path, provided the path is configured as an application.

The installation wizard will then guide you through the installation step by step, and write your web.config settings at the end of the wizard. You can manually tweak your web.config settings if you prefer, guidance on the Roadkill settings can be found on the web.config page.

If your installation fails at any point, simply change the "installed=true" in the roadkill section of your web.config to "installed=false" to reset the installation.

## Common Issues

### Web.config can't be written to
This is probably the commonest problem with the installer. If you're hosting Roadkill on shared hosting, your control panel should be able to change the permissions for the web.config. However the application pool that Roadkill is running as should have enough permissions to write to the web.config.

If you are running Roadkill on your home/development machine then the simplest solution to the problem is to run the application pool as LOCALSYSTEM or LOCALSERVICE.

### Database exceptions at Finished stage
These are almost always caused by your connection string login details or a missing dependency. The stack trace you will see on the Finished page will give you full information of the problem, if you scroll down. You can also look at the event log if you have access to it.
@@ -0,0 +1,4 @@
This is currently experimental and open to admins of the wiki only.

To view the auto-generated documentation head to the /api url on your wiki
@@ -0,0 +1,21 @@
# Searching

## Introduction
The Roadkill search engine is powered by The index is updated each time a page is created or edited. Roadkill indexes the full content of the page along with the following fields:

- id (the unique number each page is assigned)
- content
- title
- tags
- createdby (the username of the person who created the page)
- createdon (the date the page was created)

The search engine displays the first 150 characters of each page's content to display in the search summary. When you search in the textbox, the content field is searched by default. You can restrict the page to certain fields using the usual syntax found on search engines like as Google. For example:

- title:"my page"
- tags:dotnet, vb createdby:editor

## Index storage
Lucene stores index files for its search data in the App_Data/Search folder. The worker process/application pool will have rights to read and write from this folder by default, so there shouldn't be any issues with permissions providing the website root folder permissions are setup correctly.

The folder will contains 10 or more files in it, which Lucene may or may not contain file locks for while the site is running.
@@ -0,0 +1,3 @@
# Text and special: url plugins

Documentation is pending for this topic, however you can find examples of writing plugins for pre and post-markdown/creole parsing, and adding your own `special:url` urls in the [example plugins repository](
Oops, something went wrong.

0 comments on commit 271cdc6

Please sign in to comment.
You can’t perform that action at this time.