Mark up documentation in markdown rather than restructured text

joemull commented 2 years ago

Describe the area of the documentation you would like updated/added.

We have been discussing changes to the way we maintain documentation for Janeway.

Our goals:

standardize the look and feel of our documentation so that it matches with the Janeway brand
reduce the number of different places users have to go to get information about Janeway
make it easier for any member of the Janeway community to contribute documentation
- Our current markup language, ReStructured Text, has more of a learning curve than markdown
- Beginners to writing in markdown will need to be able to use the Preview tab on GitHub to see exactly what they will see in the end product

Proposed solution Three things:

Keep using readthedocs for rendering
Host the readthedocs instance on docs.janeway.systems
Convert the RST markup to Github-Flavored Markdown -- this is the work of this issue

S-Haime commented 3 months ago

File checks:

Workflow guides

[ ] Author
[ ] Reviewer
[ ] Copyeditor
[ ] Typesetter
[ ] Proofing -> Do we need to keep this?

Dev info

[ ] API
[ ] Installation
[ ] Configuration
[ ] Robots and sitemaps
[ ] Plugins
[ ] OIDC
[ ] ORCID

Editor

[ ] Editor
[ ] Prepub
[ ] Production
[ ] Proofing (needed?)
[ ] Review
[ ] Typesetting
[ ] Copyediting

Manager

[ ] Journal (index.rst)
[ ] Article issues (index)
[ ] Content (index)
[ ] Identifiers (index)
[ ] Other (index)
[ ] Other - Template_variables
[ ] Press (index)
[ ] Review (index)
[ ] Submission (index)
[ ] Users (index)

New users

[ ] GitHub intro
[ ] Janeway basics

Import plugin

[ ] Article_images
[ ] Contact_import
[ ] Copyrigt_submission_publication_reviewer
[ ] Editor_import
[ ] Editorial_team_import
[ ] Import_export_update
[ ] Index
[ ] Jats_import
[ ] Peer_review_import
[ ] Reviewer_import
[ ] Wordpress

Books plugin

[ ] Books

General

[ ] Changelog
[ ] FAQ
[ ] Styling - image guidelines
[ ] Repository
[ ] Published

Published

[ ] Articles
[ ] Issues
[ ] Schedule

S-Haime commented 3 months ago

Taken from email/ticket from Paul:

"A brief overview:

There are two main things to know about: how to upload HTML galleys and how to control their visual style with CSS.

HTML galley files can be uploaded in the same way as JATS XML galleys. Here are editor docs for generating and uploading galleys. Just make sure each file is a valid HTML document with <!DOCTYPE html> on the first line and a .html file ending. When Janeway gets an HTML file as a galley, it will just display the contents, without transforming it into HTML like it does with XML. HTML files can be previewed in the same way as XML files during typesetting and proofreading. They can be set as the main galley during prepublication as well.

For visual appearance, the process is a bit technical at the moment because it involves writing CSS rulesets that will overwrite the default styling in Janeway. So editors would need to know a bit about CSS and also how to inspect a webpage using their browser's developer tools to check that their CSS code is taking effect. Here are the two ways to put styling in:

If they want to change the styling for just one article, they can write inline CSS in the HTML document they upload.

If they want to set style rules for all the HTML galleys uploaded, they can create style sheets using the Custom Styling plugin. It looks like your installation has the plugin installed and some stylesheets set already. But editors will need staff access in Janeway to manage this plugin, so it may be better to work with them to define styles and then add a stylesheet dedicated to their journal. While editing the stylesheets, note that the results may not show up immediately. To speed up the process, you can clear the Janeway cache via "Clear Cache" the Manager page, and do a hard refresh of your browser to make sure your browser is getting the latest CSS instructions."

joemull commented 3 months ago

Closing in favor of https://github.com/BirkbeckCTP/memory-alpha/issues/25

openlibhums / janeway