FvwmWiki at GitHub

This is the source to build the FvwmWiki: http://fvwmforums.org/wiki

The wiki is built from Markdown files with front matter using Jekyll: https://jekyllrb.com.

To contribute to the wiki you will need to submit pull requests against this source.

Layout and info for contributors

The wiki is currently divided into the following main pages.

Page	Type
/	main
/Config	config
/Config/Functions	functions
/CookBook	recipe
/Tips	tip
/Modules	module
/Decor	decor
/Panels	panel
/Menus	menu
/irc	irc

Each main page generates a list of links to pages based on their type. To create a new page in one of the above lists first create a directory and index.md file for your page. For example if you wanted to put a new CookBook recipe, MyRecipe, you would create the following file

fvwmwiki/CookBook/MyRecipe/index.md

Put the following front matter at the top of your index.md file

---
layout : wiki
title : MyRecipe
type : recipe
weight : 250
description : |
  This is a multiline
  description of MyRecipe.
---

This sets the variables that are used when building. The layout must be set to "wiki" and the title is the title of your page. type, weight and description are used when building the lists on the main pages.

Set type to the type of the page you want be apart of. The weight is used to order the list. 1000 is the current top of the list and steps are by 50 or 100 to give room to put pages in between. The description is what appears below the link when describing that page in the list.

Under the front matter you then write your page using markdown syntax. Here are some notes.

• To include a table of contents built from the markdown headers use

    * TOC
    {:toc}
  

  This will float the TOC to the right. To use a full width TOC use

  * TOC
  {:toc #toc-full}  
  

• To use syntax highlighting you need to put your configuration code between special code block as follows

  {% highlight fvwm %}
  # Example Function
  DestroyFunc FuncName
  AddToFunc FuncName
  + ...
  {% endhighlight %}
  

  Non-highlighted code blocks can be generated by indenting them four spaces.

• For links between pages please use the following (so they can be built for different locations):

  [/CookBook/MyRecipe]({{ "/CookBook/MyRecipe" | prepend: site.baseurl }})
  

  This uses the variable baseurl from the _config.yml file to expand the url in the link.

• Include any images or extra files for your page in the directory alongside the index.md file

• If you want to include links your description you must write them using html.

    <a href="{{ "/CookBook/MyRecipe" | prepend: site.baseurl }}">/CookBook/MyRecipe</a>
  

  This is because the variable is not parsed through the markdown processor.

• If you want to generate your own main page, look at the current ones for examples on building a list from these variables. You need to use an index.html file to generate lists you want to be able to use links from the description variable.

Building the site with Jekyll

This static site is built from the Markdown files using Jekyll (https://jekyllrb.com/). To build the wiki you need a copy of the source and Jekyll installed. In which case the wiki can be built using

fvwmwiki# jekyll build

You can build and run a local server of the wiki with

fvwmwiki# jekyll serve

The static .html for the Wiki is built in fvwmwiki/_site. If using jekyll serve, you will be given a local address to view the Wiki on, and any changes you made will be built and updated to be viewed.

To enable syntax highlighting you will have to install a custom lexer following the steps below.

Syntax Highlighting

There is now both a python pygments and ruby rouge lexer for FVWM. From Jekyll 3 onwards rouge is the default and the one I plan to continue to work on. The pygments FvwmLexer is left as is.

Syntax Highlighting with Rouge

https://github.com/somiaj/rouge is a fork of Rouge with a lexer for Fvwm. To install this lexer I had to do the following.

• Clone the repo: git clone https://github.com/somiaj/rouge

• Install ruby, jekyll, bundler

• Install build depends, from the rouge source directory: bundle install

• Build the source: rake build

• Install the resulting .gem file: gem install rouge-2.0.7.gem

• You might have to modify jekyll to use the correct version of rouge. Find the jekyll specifications file on your system, /var/lib/gems/2.3.0/specifications/jekyll-3.3.1.gemspec on my system, then edit the runtime dependency for rogue to be ~> 2.0.7

  I also had to edit the dependencies for kramdown in a similar fashion to above.

Syntax Highlighting with Pygments

To use pygments you will need to have the python2 package pymgnets installed along with the ruby package pygments.rb to translate the python to ruby for jekyll.

Additionally you will have to install a copy of the Lexer used to create the Fvwm syntax highlighting. To do this you will need python2 and pygments installed, then install the lexer with (as root) from inside the FvwmLexer directory:

fvwmwiki/FvwmLexer# sudo python setup.py develop

This basically creates links for python to use the python script FvwmLexer/fvwmlexer/lexer.py with pygments. pygments will be using the script in the source, so any changes you make to it will update the syntax highlighting -- note you will have to kill the jekyll server and then run jekyll serve to have any changes take affect.

To test that the lexer is installed (or to use it for your own config files) run

# pygmentize -l fvwm -f html -O full config.fvwm2rc > config.html

Once you get the lexer working with pygmentize make sure that pygments.rb (ruby parser to link Jekyll with pygments) is instaled and modify _config.yml to change the highlighter from none to pygments.

highlighter: pygments

After that build (you must restart the server) to use build with syntax highlighting.

You can uninstall the lexer with easy_install

# easy_install -m fvwmlexer

This will leave an fvwmlexer.egg-link file on your system (in /usr/local/lib/python/dist-packages here).