From 44f4e1d82a2ad8fcab5c540376b0bef445389b49 Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Tue, 9 Apr 2024 14:18:27 +0200 Subject: [PATCH 1/5] Add more technical docs to the README --- README.md | 174 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 171 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ee1e0827..03f99824 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,25 @@ # NEBULA -The NEBULA (Nuxt & eScience Based Universal Learning Application) framework can be used to create an easily maintainable, version-controllable, web-based lesson collection. It is based on [Nuxt.js](https://nuxtjs.org/) and [Vue.js](https://vuejs.org/). +The NEBULA (Nuxt & eScience Based Universal Learning Application) framework can be used to create an easily maintainable, version-controllable, web-based lesson collection. It uses [Nuxt.js](https://nuxtjs.org/) and [Vue.js](https://vuejs.org/). NEBULA is being created as part of the Netherlands eScience Center Digital Skills programme. -## Documentation -Look at the [Nuxt 3 documentation](https://nuxt.com/docs/getting-started/introduction) to learn more. +# Creating content with NEBULA + +## Directory structure and content tags + +To create a platform with NEBULA the first thing that is needed is a content repository. This can be copied from the [Research Software Support example](https://github.com/esciencecenter-digital-skills/research-software-support). The repository has a few default files: + +- README.md: The documentation of your platform +- LICENSE: The license under which the content is published, by default cc-BY +- CONTRIBUTING.md: Explanation on how others can contribute to the content +- config.json: The configuration file which defines its name/title, styling, organization and categories. + +The `.github` directory holds the workflow files that are necessary to serve the platform on github pages, as well as additional tests and checks. All content lives in the `modules` directory. + +Most modules are already set up: they contain a `{modulename}.md` file, as well as a `_modulename/` directory. +If your module is not yet set up, please create both these inside the `modules` directory. ## Setup @@ -67,3 +80,158 @@ yarn preview ``` Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information. + + +### The `_modulename/` directory + +Any files that are relevant for the module should be placed in the `_modulename/` directory. +This includes images that are linked in the `modulename.md` file, as well as slides, and images used in the slides. + +When embedding images in the `modulename.md` file or slides, please use the following path: `stories/_modulename/image.png`. +While technically possible, because we want the modules to be transportable, please avoid using images from other modules. + +### The `modulename.md` file + +#### YAML header + +The module starts with a YAML header. +For instance, the header for the SMP module looks like this: + +```yaml +--- +id: 1 +trl: medium +category: Reusability +title: Software Management Plans +author: eScience Center +thumbnail: "nlesc-dummy.png" +--- +``` + +The only important fields at this point are `category`, `title`, and `thumbnail`. + +The `category` field should be one of the categories mentioned on the [main page](https://esciencecenter-digital-skills.github.io/research-software-support/). +Any changes to the order of categories or their names should be set in the config.json file, in the root directory. +The `title` field should be the title of the module; it will be shown on the main overview page. +The `thumbnail` field should be the name of the thumbnail image, which should be placed in the `static/stories/_modulename/` directory. +This image shows up on the index page. +Eventually, we will use customized icons for this; currently, we use dummy images. +Check any of the existing modules for an example. + +The `id`, `author` and `trl` (technical readiness level) properties are currently not used, but they are still here for legacy reasons. + +Note that the path to the thumbnail image is relative to the `_modulename/` directory, as opposed to any images inside the text. + +#### Chapters + +A chapter (i.e. the content in a single tab) is fenced by triple colons, as follows: + +```markdown +:::Chapter{headline="Why an SMP?" widemd=1} + +A software management plan (SMP) can help you! +::: +``` + +The `headline` field is the title of the of the chapter tab. +Meanwhile, `widemd=1` indicates that the chapter type is text-based. For more information on the various chapter types, see [below](#chapter-types). + +Between the colons, you can use markdown to format the text. + +#### Chapter types + +A chapter of a module will render as a tab in the horizontal navigation bar. Currently two types of + +### Slides with Reveal.js + +Slides should be placed in the `/modules/{modulename}/` directory as a markdown file with the special extension `.pmd`, for example: `presentation.pmd`. + +The slides are written in Markdown with some extra additions, and rendered using [Reveal.js](https://revealjs.com/). + +#### Slide types + +At the moment only eScience themed slides are supported. There are currently four different slide types: + +- Title slide, `data-state="title"` +- Default slide, `data-state="standard"` +- "About us", `data-state="about"` +- "Let's stay in touch", `data-state="keepintouch"` + +A slide is fenced by three dashes, and (optionally) an HTML comment that indicates the slide type: + +```markdown + + + +This is a standard slide. + +--- + + + +My name is ... + +--- + +``` + +Always keep an empty line before and after the slide fence. + +The dashes indicate the slide borders; the are therefore only necessary between the slides, and not at the beginning or end of a presentation. + +#### Slide content + +Slide content can be written in Markdown. + +To keep slides clean, use single images per slide. +Styling in Reveal is not trivial, and it is best to keep it simple. + +Images can be embedded using either markdown syntax: + +```markdown +![Mapping the Via Appia](stories/_smp/viaappia.png) +``` + +Or, for more customisation, using HTML: + +```html +
+ +
+``` + +#### Slide notes + +Notes should be added at the bottom of the slide, as follows: + +```markdown + +Note: +Here is the text of a note. + +--- +``` + +where the `---` indicates the fence to the following slide. + +#### Final slide + +The final slide should provide the contact information for the eScience Center. +This is not hardcoded into the slides, so it should be provided explicitly. + +The code for the final slide is as follows: + +```markdown + +--- + + + + +www.esciencecenter.nl + +info@esciencecenter.nl + +020 - 460 47 70 + +``` \ No newline at end of file From 2983a2ec32e08e0e41580378fc9d7c676a293c6c Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Wed, 10 Apr 2024 17:54:26 +0200 Subject: [PATCH 2/5] simplify installation section of Readme --- README.md | 28 ++-------------------------- 1 file changed, 2 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 03f99824..306921a7 100644 --- a/README.md +++ b/README.md @@ -28,42 +28,24 @@ Make sure to install the dependencies: ```bash # npm npm install - -# pnpm -pnpm install - -# yarn -yarn install ``` -## Development Server +### Development Server Start the development server on `http://localhost:3000`: ```bash # npm npm run dev - -# pnpm -pnpm run dev - -# yarn -yarn dev ``` -## Production +### Production Build the application for production: ```bash # npm npm run build - -# pnpm -pnpm run build - -# yarn -yarn build ``` Locally preview production build: @@ -71,12 +53,6 @@ Locally preview production build: ```bash # npm npm run preview - -# pnpm -pnpm run preview - -# yarn -yarn preview ``` Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information. From 9bca685d62fda76f3d1eacc204d3bfdd5a2594a9 Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Fri, 31 May 2024 16:14:29 +0200 Subject: [PATCH 3/5] Update README, remove elaborate docs --- README.md | 201 ++++-------------------------------------------------- 1 file changed, 15 insertions(+), 186 deletions(-) diff --git a/README.md b/README.md index 306921a7..b55f473c 100644 --- a/README.md +++ b/README.md @@ -1,213 +1,42 @@ +[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/esciencecenter-digital-skills/NEBULA/blob/main/LICENSE) + # NEBULA +Copyright 2023-2024 Netherlands eScience Center + The NEBULA (Nuxt & eScience Based Universal Learning Application) framework can be used to create an easily maintainable, version-controllable, web-based lesson collection. It uses [Nuxt.js](https://nuxtjs.org/) and [Vue.js](https://vuejs.org/). NEBULA is being created as part of the Netherlands eScience Center Digital Skills programme. +For elaborate setup instructions and other documentation, see the [NEBULA documentation](https://github.com/esciencecenter-digital-skills/NEBULA-docs) -# Creating content with NEBULA - -## Directory structure and content tags -To create a platform with NEBULA the first thing that is needed is a content repository. This can be copied from the [Research Software Support example](https://github.com/esciencecenter-digital-skills/research-software-support). The repository has a few default files: +# Quick setup -- README.md: The documentation of your platform -- LICENSE: The license under which the content is published, by default cc-BY -- CONTRIBUTING.md: Explanation on how others can contribute to the content -- config.json: The configuration file which defines its name/title, styling, organization and categories. +## Content directory/repository -The `.github` directory holds the workflow files that are necessary to serve the platform on github pages, as well as additional tests and checks. All content lives in the `modules` directory. +To use NEBULA you will need to setup a content directory or repository. See the [NEBULA content template repository](https://github.com/esciencecenter-digital-skills/NEBULA-content-template) or the [NEBULA documentation on creating content](https://github.com/esciencecenter-digital-skills/NEBULA-docs/blob/add_local_rendering_docs/content-repo-instantiation.md) for more information. -Most modules are already set up: they contain a `{modulename}.md` file, as well as a `_modulename/` directory. -If your module is not yet set up, please create both these inside the `modules` directory. +## Install dependencies -## Setup - -Make sure to install the dependencies: +Install the dependencies using the node package manager: ```bash # npm npm install ``` -### Development Server - -Start the development server on `http://localhost:3000`: +## Link to the content directory ```bash -# npm -npm run dev +export CONTENT_PATH="~/path/to/your/content/directory" ``` -### Production - -Build the application for production: +## Local development build -```bash -# npm -npm run build -``` - -Locally preview production build: +Start the development server on `http://localhost:3000`: ```bash # npm -npm run preview -``` - -Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information. - - -### The `_modulename/` directory - -Any files that are relevant for the module should be placed in the `_modulename/` directory. -This includes images that are linked in the `modulename.md` file, as well as slides, and images used in the slides. - -When embedding images in the `modulename.md` file or slides, please use the following path: `stories/_modulename/image.png`. -While technically possible, because we want the modules to be transportable, please avoid using images from other modules. - -### The `modulename.md` file - -#### YAML header - -The module starts with a YAML header. -For instance, the header for the SMP module looks like this: - -```yaml ---- -id: 1 -trl: medium -category: Reusability -title: Software Management Plans -author: eScience Center -thumbnail: "nlesc-dummy.png" ---- -``` - -The only important fields at this point are `category`, `title`, and `thumbnail`. - -The `category` field should be one of the categories mentioned on the [main page](https://esciencecenter-digital-skills.github.io/research-software-support/). -Any changes to the order of categories or their names should be set in the config.json file, in the root directory. -The `title` field should be the title of the module; it will be shown on the main overview page. -The `thumbnail` field should be the name of the thumbnail image, which should be placed in the `static/stories/_modulename/` directory. -This image shows up on the index page. -Eventually, we will use customized icons for this; currently, we use dummy images. -Check any of the existing modules for an example. - -The `id`, `author` and `trl` (technical readiness level) properties are currently not used, but they are still here for legacy reasons. - -Note that the path to the thumbnail image is relative to the `_modulename/` directory, as opposed to any images inside the text. - -#### Chapters - -A chapter (i.e. the content in a single tab) is fenced by triple colons, as follows: - -```markdown -:::Chapter{headline="Why an SMP?" widemd=1} - -A software management plan (SMP) can help you! -::: -``` - -The `headline` field is the title of the of the chapter tab. -Meanwhile, `widemd=1` indicates that the chapter type is text-based. For more information on the various chapter types, see [below](#chapter-types). - -Between the colons, you can use markdown to format the text. - -#### Chapter types - -A chapter of a module will render as a tab in the horizontal navigation bar. Currently two types of - -### Slides with Reveal.js - -Slides should be placed in the `/modules/{modulename}/` directory as a markdown file with the special extension `.pmd`, for example: `presentation.pmd`. - -The slides are written in Markdown with some extra additions, and rendered using [Reveal.js](https://revealjs.com/). - -#### Slide types - -At the moment only eScience themed slides are supported. There are currently four different slide types: - -- Title slide, `data-state="title"` -- Default slide, `data-state="standard"` -- "About us", `data-state="about"` -- "Let's stay in touch", `data-state="keepintouch"` - -A slide is fenced by three dashes, and (optionally) an HTML comment that indicates the slide type: - -```markdown - - - -This is a standard slide. - ---- - - - -My name is ... - ---- - -``` - -Always keep an empty line before and after the slide fence. - -The dashes indicate the slide borders; the are therefore only necessary between the slides, and not at the beginning or end of a presentation. - -#### Slide content - -Slide content can be written in Markdown. - -To keep slides clean, use single images per slide. -Styling in Reveal is not trivial, and it is best to keep it simple. - -Images can be embedded using either markdown syntax: - -```markdown -![Mapping the Via Appia](stories/_smp/viaappia.png) -``` - -Or, for more customisation, using HTML: - -```html -
- -
-``` - -#### Slide notes - -Notes should be added at the bottom of the slide, as follows: - -```markdown - -Note: -Here is the text of a note. - ---- -``` - -where the `---` indicates the fence to the following slide. - -#### Final slide - -The final slide should provide the contact information for the eScience Center. -This is not hardcoded into the slides, so it should be provided explicitly. - -The code for the final slide is as follows: - -```markdown - ---- - - - - -www.esciencecenter.nl - -info@esciencecenter.nl - -020 - 460 47 70 - +npm run dev ``` \ No newline at end of file From 7ec41a7d7745ed779fa2996dfd43a4b992329e53 Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Fri, 31 May 2024 16:26:23 +0200 Subject: [PATCH 4/5] add contributing guidelines and link in the readme --- CONTRIBUTING.md | 9 +++++++++ README.md | 8 ++++++-- 2 files changed, 15 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..e8993d51 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,9 @@ +# Contributing to NEBULA + +We welcome any support on maintaining and developing the NEBULA framework. + +## How can I contribute? + +If you have an issue with NEBULA: look whether the issue you have [already exists](https://github.com/esciencecenter-digital-skills/NEBULA/issues) or make a [new issue](https://github.com/esciencecenter-digital-skills/NEBULA/issues/new), and [create a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) with your changes from a fork or a branch. + +If you want to contribute but do not know where to start, look for [an issue you can pick up](https://github.com/esciencecenter-digital-skills/NEBULA/issues), or contact the development team via j.camphuijsen@esciencecenter.nl for more guidance. diff --git a/README.md b/README.md index b55f473c..50768632 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ For elaborate setup instructions and other documentation, see the [NEBULA docume ## Content directory/repository -To use NEBULA you will need to setup a content directory or repository. See the [NEBULA content template repository](https://github.com/esciencecenter-digital-skills/NEBULA-content-template) or the [NEBULA documentation on creating content](https://github.com/esciencecenter-digital-skills/NEBULA-docs/blob/add_local_rendering_docs/content-repo-instantiation.md) for more information. +To use NEBULA you will need to setup a content directory or repository. See the [NEBULA content template repository](https://github.com/esciencecenter-digital-skills/NEBULA-content-template) or the [NEBULA documentation on creating content](https://github.com/esciencecenter-digital-skills/NEBULA-docs/blob/main/content-repo-instantiation.md) for more information. ## Install dependencies @@ -39,4 +39,8 @@ Start the development server on `http://localhost:3000`: ```bash # npm npm run dev -``` \ No newline at end of file +``` + +# Contributing + +If you want to contribute to the NEBULA framework, please read the [contributing guidelines](https://github.com/esciencecenter-digital-skills/NEBULA/blob/main/CONTRIBUTING.md). \ No newline at end of file From a3f5a523cd71636bba7e55096cffea2e288a3173 Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Wed, 5 Jun 2024 20:48:09 +0200 Subject: [PATCH 5/5] Switch setup steps to avoid error --- README.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 50768632..1fa1bb4c 100644 --- a/README.md +++ b/README.md @@ -17,19 +17,23 @@ For elaborate setup instructions and other documentation, see the [NEBULA docume To use NEBULA you will need to setup a content directory or repository. See the [NEBULA content template repository](https://github.com/esciencecenter-digital-skills/NEBULA-content-template) or the [NEBULA documentation on creating content](https://github.com/esciencecenter-digital-skills/NEBULA-docs/blob/main/content-repo-instantiation.md) for more information. -## Install dependencies -Install the dependencies using the node package manager: +## Link to the content directory + +To make sure that NEBULA knows which content to build, we create the following environment variable: ```bash -# npm -npm install +export CONTENT_PATH="~/path/to/your/content/directory" ``` -## Link to the content directory + +## Install dependencies + +Install the dependencies using the node package manager: ```bash -export CONTENT_PATH="~/path/to/your/content/directory" +# npm +npm install ``` ## Local development build