Skip to content
This repository has been archived by the owner on Sep 24, 2021. It is now read-only.

stanford-rc/docs-farmshare

Repository files navigation

Farmshare Documentation

This is the Farmshare (version 2) documentation base. It is driven by mkdocs-jekyll.


Usage

1. Get the code

You can clone the repository:

git clone https://github.com/stanford-rc/docs-farmshare.git

2. Customize

Generally, you should see the the getting started guide for the template to better understand how to add custom elements, link to pages, create page tags, etc. A brief overview is provided here.

How do I add pages?

Documentation pages are found in [_docs/docs], and you can add them as links to other pages, or in the navigation directly by editing _data/toc.myl. For more regular pages (e.g., "About") you can put them in the pages folder, and optionally add a permalink value to define the URL.

How do I edit metadata?

To edit configuration values, customize the _config.yml. Most of the configuration values in the _config.yml are self explanatory, and for more details, see the about page rendered on the site.

How do I add alerts, boxes, and other elements?

See the getting started guide for the template.

3. Serve

Depending on how you installed jekyll:

jekyll serve
# or
bundle exec jekyll serve

Development

The Drupal site hosted at Farmshare 2 was first extracted manually via the web interface. The raw files are in src. First, we needed to download the scripts to help wit conversion. There is one for each of conversion from mediawiki, and from html.

$ wget -O scripts/mw2md.py https://raw.githubusercontent.com/vsoch/mw2md.py/master/mw2md.py
$ wget -O scripts/mw2md.py https://raw.githubusercontent.com/vsoch/mw2md.py/master/html2md.py

Install dependencies for the html conversion (markdownify):

$ pip install -r scripts/requirements.txt

Create the docs folder:

$ mkdir -p docs

And then convert the MediaWiki file:

$ python scripts/mw2md.py src/mobaxterm.txt > docs/mobaxterm.md

And then the html files:

for filename in $(ls src/*.html); do
    name=$(basename -- "$filename")
    name="${name%.*}"
    markdown="docs/${name}.md"
    if [ ! -f "${markdown}" ]; then
        echo "Converting $filename to $markdown"
        python scripts/html2md.py $filename $markdown
    fi
done

Note that after conversion, some manual work was done to fix tables (which weren't parsed) and code blocks.

And finally, moving images to be relative to the docs folder.

$ cp -R src/img docs/img