Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
Corrected callout important
  • Loading branch information
albarema authored Mar 1, 2024
1 parent 7c7f3ab commit 27ff1f4
Showing 1 changed file with 11 additions and 10 deletions.
21 changes: 11 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,10 +55,11 @@ Check out [this link](https://quarto.org/docs/output-formats/html-themes.html) f

### bioschemas

Finally, there is a commented section that includes a bioschema as part of the webpage header. The [bioschema](https://bioschemas.org/) is in an HTML file, whose script is always executed by the deployed webpage.
Finally, there is a commented-out section that includes a bioschema as part of the webpage header. The [bioschema](https://bioschemas.org/) is in an HTML file, whose script is always executed by the deployed webpage.

!!! important
Uncomment this part of the configuration **only upon finalization of your website** - so that it will be published on the Elixir TeSS database with the appropriate finish content.
::: {.callout-important}
Uncomment this part of the configuration **only upon finalization of your website** - so that it will be published on the Elixir TeSS database with the appropriate finished content.
:::

Take a look at `resources/bioschema.html` to see how the bioschema is structured. It is essentially a `JSON` table containing standard descriptors such as course name, type, audience, datasets and more.

Expand Down Expand Up @@ -97,7 +98,7 @@ Take a look at `resources/bioschema.html` to see how the bioschema is structured
}
```

The example above includes the schema standard, `@context`, which is fixed. It also contains the link to the course, `@id`, and specifies that it is a learning resource, `@type`. Additionally, you will find keywords, the type of learning resource and a user license. The `mentions` item allows you to create multiple objects of `@type: Thing` with a link (`@id`). These could be datasets, slides, and other open material. Finally, you have a few other descriptors for the course.
The example above includes the schema standard, `@context`, which is fixed. It also contains the link to the course, `@id`, and specifies that it is a learning resource, `@type`. Additionally, you will find keywords, the type of learning resource, and a user license. The `mentions` item allows you to create multiple objects of `@type: Thing` with a link (`@id`). These could be datasets, slides, and other open material. Finally, you have a few other descriptors for the course.

For a more complete example, refer to the file `resources/bioschema_example.html` for inspiration. You can explore all the terms that can be used in a bioschema by looking at the [bioschemas for training material](https://bioschemas.org/profiles/TrainingMaterial/1.0-RELEASE). To verify your bioschema, you can either: a. Copy and paste the code from `bioschema.html`, b. Use the published webpage address (once it is published with the bioschema included in the configuration file) [here](https://validator.schema.org/). This will provide a report on the elements of the bioschema.

Expand All @@ -107,15 +108,15 @@ A standard webpage is in `qmd` format, which is essentially a markdown document

## Adding Rmd files

`R markdown`, or abbreviated as `Rmd`, files can be used as webpages (as indicated by one of the menu items in the configuration file). However, this files need to be knitted and executed, so you need all the relevant R packages to be installed. Once processed, the `Rmd` file will become a visually nice looking webpage, where you can also include bibliography references. Look at the example page `rmd/rmarkdown_example.Rmd` to better understand how things need to be coded.
`R markdown`, or abbreviated as `Rmd`, files can be used as webpages (as indicated by one of the menu items in the configuration file). However, these files need to be knitted and executed, so you need all the relevant R packages to be installed. Once processed, the `Rmd` file will become a visually nice-looking webpage, where you can also include bibliography references. Look at the example page `rmd/rmarkdown_example.Rmd` to better understand how things need to be coded.

## Adding jupyter notebooks
## Adding Jupyter Notebooks

Files in `ipynb` format can similarly be used as webpages, with the advantage that they don't require compilation. They are read as-is and converted into a we format directly. Interactive plots, if present, should function properly on the webpage.
Files in `ipynb` format can similarly be used as webpages, with the advantage that they don't require compilation. They are read as-is and converted into a web format directly. Interactive plots, if present, should function properly on the webpage.

## Listing people

You can create pages containing lists (such as listing blog items or other lists). In our example, `people.qmd` has a specific metadata dedicated to this purpose:
You can create pages containing lists (such as listing blog items or other lists). In our example, `people.qmd` has specific metadata dedicated to this purpose:

```yml
---
Expand All @@ -132,9 +133,9 @@ The webpage aims to display the people involved in the sandbox project. Each per

If you want to see the webpage under development, you can simply run the command `quarto preview` from your command line while inside the folder with the configuration file.

The webpage can be published by simply pushing it on Github. There is a Github workflow in the folder `.github\workflows\publish.yml` which does all of that. Unfortunately, if you need additional `R` packages, then you have to change the workflow on your own. You can do this by taking a `snapshot` of the R you use for development (after loading all required packages). That should produce a file called `renv.lock` you can use to substitute the one present in this repository. Read more on R environments [here](https://github.com/hds-sandbox/ucloud_development/blob/main/ucloud_develop_docs.md#rstudio-based-apps).
The webpage can be published by simply pushing it on Github. There is a Github workflow in the folder `.github\workflows\publish.yml` which does all of that. Unfortunately, if you need additional `R` packages, then you have to change the workflow on your own. You can do this by taking a `snapshot` of the R you use for development (after loading all required packages). That should produce a file called `renv.lock` that you can use to substitute the one present in this repository. Read more on R environments [here](https://github.com/hds-sandbox/ucloud_development/blob/main/ucloud_develop_docs.md#rstudio-based-apps).

It can be very annoying trying to make the workflow work and testing it until it does. You can also deploy manually the webpage by:

* deleting the workflow file `.github\workflows\publish.yml` (which will otherwise always try to run)
* run `quarto publish gh-pages` on your command line
* run `quarto publish gh-pages` on your command line

0 comments on commit 27ff1f4

Please sign in to comment.