[FIX] misc minor fixes to the documentation (#482)

* add syntax highlighting where missing

* move files in subfolders

* rename files

* update contributing info

* format markdown

* apply remark

* fix links

* fix file name

* apply review suggestions

* fix filenames in mkdocs.yml

.gitignore

@@ -1,6 +1,11 @@
 .DS_Store
-.idea/
 activities/.DS_Store
 protocols/.DS_Store
+
+.idea/
+
 node_modules
 local_data
+
+package-lock.json
+package.json

.pre-commit-config.yaml

@@ -10,6 +10,7 @@ repos:
     -   id: check-json
     -   id: check-ast
     -   id: check-added-large-files
+    -   id: check-merge-conflict
 -   repo: https://github.com/psf/black
     rev: 24.3.0
     hooks:

.remarkrc

@@ -0,0 +1,18 @@
+{
+  "plugins": [
+    "preset-lint-markdown-style-guide",
+    "preset-lint-recommended",
+    "remark-gfm",
+    ["lint-no-duplicate-headings", false],
+    ["lint-list-item-indent", "tab-size"],
+    ["lint-emphasis-marker", "consistent"],
+    ["lint-maximum-line-length", 500],
+    ["lint-maximum-heading-length", false],
+    ["lint-no-shortcut-reference-link", false],
+    ["remark-lint-unordered-list-marker-style", "-"],
+    ["lint-no-trailing-spaces"],
+    ["remark-lint-code-block-style", false],
+    ["lint-no-undefined-references", false],
+    ["remark-lint-heading-style", false]
+  ]
+}

README.md

@@ -39,7 +39,7 @@ following libraries via pip
 
 To make a new release:
 
-```
+```bash
 python scripts/makeRelease.py <version>
 python scripts/editProperties.py <version>
 ```

docs/100_about_this_doc.md → docs/CONTRIBUTING.md

@@ -1,15 +1,18 @@
-# About this documentation
+# Contributing
 
-This documentation is a work in progress and we wellcome any input: if something is missing or unclear, let us know by [opening an issue on our repository] (???).
+## Contributing to the documentation
 
-## Serving the doc locally
+This documentation is a work in progress and we wellcome any input:
+if something is missing or unclear, let us know by opening an issue on our repository.
+
+### Serving the doc locally
 
 This project uses [MkDocs](https://www.mkdocs.org/) tool with [Material theme](https://squidfunk.github.io/mkdocs-material/)
 and extra plugins to generate the website.
 
 To test locally, you will need to install the Python dependencies. To do that, type the following commands:
 
-```
+```bash
 git clone https://github.com/ReproNim/reproschema.git
 cd reproschema
 pip install -r requirements.txt
@@ -20,7 +23,7 @@ by `git clone [email protected]/<username>/reproschema.git` where `<username>` is y
 
 Once done, you need to run MkDocs. Simply type:
 
-```
+```bash
 mkdocs serve
 ```
 

docs/FAQ.md

@@ -0,0 +1,49 @@
+# FAQ
+
+<!--
+## Why should I use ReproSchema?
+
+**🛠 Work in progress 🛠**
+
+## Who is ReproSchema for?
+
+**🛠 Work in progress 🛠**
+
+## How can I know if a certain property is supported by ReproSchema?
+
+**🛠 Work in progress 🛠**
+
+## How can I add a property to my schema?
+
+**🛠 Work in progress 🛠**
+
+## How are these assessments licensed?
+
+**🛠 Work in progress 🛠**
+
+## How can I contribute to the project?
+
+**🛠 Work in progress 🛠**
+
+## An assessment tool I regularly use is not supported by ReproSchema: how can I add it?
+
+**🛠 Work in progress 🛠**
+-->
+
+## How can I visualize the schema for a `protocol` or an `activity`?
+
+If you want to see what the assessment that are already supported by the ReproSchema would look like using our ReproSchema user-interface, you can visualize them directly on [schema.repronim.org](https://schema.repronim.org/rl).
+
+If you just want to view a protocol or activity you are developing using the `reproschema-ui`, you can pass the URL of the schema to the `url` query parameter like this:
+
+```https://schema.repronim.org/ui/#/?url=url-to-your-schema```
+
+If you are hosting a schema on github, make sure that you are passing the URL of the **raw** content of the schema. For example, our demo protocol can be accessed at this URL:
+
+[https://github.com/ReproNim/reproschema-demo-protocol/blob/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://github.com/ReproNim/reproschema-demo-protocol/blob/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema)
+
+But to get access to the raw content of that file you must click on the `Raw` button once you have opened that page on github that will open this URL:
+
+[https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema).
+
+If you want to visualize the graph represented by the JSON-LD file, we explain how to do this in [From JSON to JSON-LD](#from-json-to-json-ld).