Rel4tion-Wiki/editing/help/page-types.mdwn

Regular pages are Markdown files with [[ikiwiki]] extensions. But there may be
other file types you want to put on the wiki, for example:

- Pages with other markup, e.g. *Creole*
- Source code, e.g. *.pl* and *.py* files
- Plain text without Markdown features
- Custom file extensions and syntaxes
- Non-page files, e.g. images

The following sections explain how to use various page types. For non-page
files, see the other [[editing/help]] pages.

# Other Markup

Currently Markdown is the only markup used for text pages, and I prefer that all
pages are written consistently with the same markup, unless special features are
required (e.g. TeX).

New markup formats can be enabled by plugins if needed - ikiwiki supports
several popular formats.

# Source Code

Using the [[ikiwiki/directive/format]] directive, it is possible to embed
syntax-highlighted text inside pages. But in order to have while source files
highlighted and rendered like regular wiki pages, i.e. with links and headers,
their file types need to be added to the wiki setup file.

Currently several common types are enabled, such as Perl and Python. More types
can be easily added to the setup file. Then, just use the source files as-is in
the wiki source tree and they will be rendered into highlighted wiki pages.

# Plain Text

There are two ways to create plain-text files: With ikiwiki and Markdown
features, and without. The first option works just like when uploading source
files, but without the syntax highlighting, i.e. "plain text" file type. By
default the highlight plugin maps the *txt* extension to plain text, i.e. you
can create *.txt* files and they'll be rendered into pages.

For simple use, this setup works even if you don't want Markdown or WikiLinks
in your file.

For the second option, i.e. real plain-text without wiki features, the txt
plugin should be enabled.

It is also possible to have other extensions as plain-text file extensions, e.g.
for special purpose files like license text (COPYING) or song lyrics. These
extensions can be specified in the setup file. Several such extensions are
already in use in this wiki, and are mentioned below.

# Song Lyrics

It is possible to create pages for song lyrics as-is, i.e. consecutive lines
won't be merged into paragraphs and the lyrics will appear like in the source
text. It works by adding a page with a __.lyrics__ extension.

Lyrics pages are handled by the highlight plugin as plain-text files.

Example: [[people/fr33domlover/song-lyrics/john_lennon/imagine.lyrics]]

# IRC Logs

It is possible to create pages for IRC logs, like the ones which can be exported
by XChat. They will be highlighted. It works by adding a page with an __.irc__
extension.

IRC log pages are handled by the highlight plugin. Curretly they are highlighted
as HTML pages because it's close enough to the log syntax to make the result
readable, but it's not perfect.

[[TODO|TODO/OPEN]] consider trying to develop GNU source-highlight support for
ikiwiki

[[TODO|TODO/OPEN]] write a syntax file for IRC logs, either for 'highlight' or for
GNU source-highlight

Work on the syntax highlighting is happening [[here|irc-log-highlight]].

Example: [[TODO|TODO/OPEN]] add example link