Documentation with Markdown
There is now a directory to contain Markdown documentation: https://github.com/pombase/website/tree/master/src/docs
The plan is to have a sub-directory of docs for each of the documentation paths (so "about/", "help/", "community/" etc.)
Each directory will also contain a "menu.md" file containing the Markdown that should appear in the menu at the left. And an "index.md" which contains the content you should see when you go to eg. http://www.pombase.org/community/ (ie. you go to a section but don't specify which page)
See also: Generating-documentation-HTML-after-Markdown-is-added-or-edited
Here's an example Markdown file: https://raw.githubusercontent.com/pombase/website/master/src/docs/community/fission-yeast-community-curation-project.md
GitHub renders Markdown into nice HTML by default: https://github.com/pombase/website/blob/master/src/docs/community/fission-yeast-community-curation-project.md
The pages can be edited online via GitHub or locally. GitHub renders the Markdown files as HTML so you can view them live(-ish). Unfortunately it does a bad job on tables that don't have headers. eg. https://github.com/pombase/website/blob/master/src/docs/about/index.md
This editor shows the HTML version of the Markdown text as you type, including tables: https://stackedit.io/editor
If you have a table with a header it needs to be formatted like this:
|some header | other header|
|------------|-------------|
|value 1 | value 2 |
|some data | other data |
which renders as:
| some header | other header |
|---|---|
| value 1 | value 2 |
| some data | other data |
The amount of whitespace doesn't matter and the numbers dashes doesn't either. So that second like could be: "|-|-|"
You need as many sets of dashes as you have columns. eg. "|-|-|-|" for a three column table.
If you don't have a header you still need the "|-|-|" for it to display properly on the web site. It won't display properly on GitHub without a header though.
Here's a tool for creating tables in the right format:
- http://www.tablesgenerator.com/markdown_tables It can even import CSV files.
For the PomBase v2 pages the markdown files are being processed with Pandoc which has a very comprehensive implementation of Markdown: http://pandoc.org/MANUAL.html#pandocs-markdown
Pandoc has lots of options and features so I'm sure it will cope with most of our documentation needs.
One helpful Markdown feature that we may need is the ability to stick arbitrary HTML in the file. This might help with moving some of the more complicated pages across
eg.
- some list item
- other item
<bold>
BOLD text
</bold>
<img src="https://www.pombase.org/assets/pombase-logo.png"/>
# Some other text
renders as:
- some list item
- other item
BOLD text
If you need to link to another page in PomBase v2, use path without the https://www.pombase.org/ bit. eg. [Mailing lists](community/mailing-lists)
There are two examples in the menu.md for the community section: https://raw.githubusercontent.com/pombase/website/master/src/docs/community/menu.md
You can link to any page, including gene pages. eg. [cdc2 page](gene/SPCC1739.11c)
The syntax is:
<app-query-link [goToResults]="true" [linkText]="'Some description'"
[predefinedQueryId]="'some_predefined_query_id'">
</app-query-link>
Where some_predefined_query_id is the ID of a predefined query in the config file
The Some description can be text except single and double quotes. The surrounding single and double quotes are required. To have a double quote appear on the web page use the HTML escape sequence ". eg.
[linkText]="'Quote just "one" word'"
The magic (and ugly) directive to start a database specific section is:
%%if db=PomBase
And to end a section:
%%end db=PomBase
Example:
## some heading
This text will be included in both PomBase and JaponicusDB.
%%if db=PomBase
This text will only appear in the PomBase documentation.
%%end db=PomBase
Some text for both DBs.
%%if db=JaponicusDB
Some documentation for JaponicusDB
%%end db=JaponicusDB
To include part of a line or paragraph, split the line and insert the magic directive with no blank lines around it. For example for this bit from advanced-search.md:
3. Select columns to display. A set of gene expression data sets are
hidden by default; click "Show gene expression columns" to reveal the
additional options.
the second sentence can be made PomBase only like this:
3. Select columns to display.
%%if db=PomBase
A set of gene expression data sets are
hidden by default; click "Show gene expression columns" to reveal the
additional options.
%%end db=PomBase
For PomBase that's equivalent to:
3. Select columns to display.
A set of gene expression data sets are
hidden by default; click "Show gene expression columns" to reveal the
additional options.
Otherwise it's:
3. Select columns to display.
It's possible to use variables to substitute things like database name and various ways of presenting organism names into the HTML.
Here is an example of this in advanced-search.md:
The ${database_name} advanced search allows you to construct complex queries
for ${species_abbrev} genes. At present all advanced search results are lists
of genes that match the query specifications. Hints for specific
searches are available in the [PomBase FAQ](/faq), and linked
[below](#search-tips).
for Pombase this is the same as:
The PomBase advanced search allows you to construct complex queries
for *S. pombe* genes. At present all advanced search results are lists
of genes that match the query specifications. Hints for specific
searches are available in the [PomBase FAQ](/faq), and linked
[below](#search-tips).
These are the possible variables and their values:
| String in Markdown | PomBase result in HTML | JaponicusDB result |
|---|---|---|
${database_name} |
PomBase | JaponicusDB |
${lc_database_name} |
pombase | japonicusdb |
${genus_and_species} |
Schizosaccharomyces pombe | Schizosaccharomyces japonicus |
${genus} |
Schizosaccharomyces | Schizosaccharomyces |
${species} |
pombe | japonicus |
${species_abbrev} |
S. pombe | S. japonicus |
${ncbi_taxon_id} |
4896 | 4897 |
${base_url} |
https://www.pombase.org |
https://www.japonicusdb.org |
${helpdesk_address} |
(helpdesk at pombase dot org) |
It's possible to arrange for specific ".md" files to be included in the documentation for only one database.
For example to include the pombe sequencing-status documentation only in PomBase we can use the filename:
src/docs/status/sequencing-status.PomBase.md
instead of:
src/docs/status/sequencing-status.md
If it makes sense to have a similar page for japonicus, we'd make a file named:
src/docs/status/sequencing-status.JaponicusDB.md
If we didn't want a japonicus status page we would need to remove the links to the sequencing-status page too. For example in src/docs/status/index.md we would need to wrap the table row the includes the link in the conditional directives:
...
| [Genome statistics](status/statistics) | Latest information on the status of the genome |
%%if db=PomBase
| [Sequencing status](status/sequencing-status) | Contig size, gap status and progress, including [centromeres](status/centromeres) and [telomeres](status/telomeres) |
%%end db=PomBase
| [Sequence updates](status/sequencing-updates) | Changes to the genome sequence since July 2003 |
| [Sequence updates pending](status/sequence-updates-pending) | Pending changes, mainly from the Broad Institute, some supported by data from other sources |
...Note that the link to a DB specific file should not include the .PomBase/.JaponicusDB suffix as the processing script sorts that out. So we use something like: [Sequencing status](status/sequencing-status)
PomBase News items should be added to this directory: https://github.com/pombase/website/tree/master/src/docs/news.PomBase/
(JaponicusDB news has a separate directory)
The file names should begin with the date in ISO format and end with ".md" eg. "2018-10-24-some-new-news-item.md"
Each file should contain a ### header as it's first line. eg.
### New book chapter about PomBase
There are two optional directives that can be added just after the header:
<!-- pombase_flags: frontpage -->
<!-- newsfeed_thumbnail: book_chapter.png -->
The <!-- pombase_flags: frontpage --> directive will make the item appear on the front page.
The <!-- newsfeed_thumbnail: book_chapter.png --> directive specifies the thumbnail to use (if any). The thumbnail images should be 32x32 pixels and should be added to this directory: https://github.com/pombase/website/tree/master/src/assets/newsfeed/
FAQ items should be added to this directory: https://github.com/pombase/website/tree/master/src/docs/faq/
The file names should end with ".md"
Each file should contain a # header as it's first line. eg.
# Can I download all *S. pombe* phenotype data?
A pombase_categories directive should be added just under the header line:
<!-- pombase_categories: Finding data,Using ontologies -->
If the FAQ file does not contain a pombase_categories directive it won't appear in any category.