From 4f0e04fe0a8eda6ffcc942f040637c4ce5a38af9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Mantelet?= Date: Thu, 28 Nov 2024 16:32:58 +0100 Subject: [PATCH 1/4] Add a newsletter Archetype (i.e. template for newsletters) --- CONTRIBUTING.md | 23 +++++++ archetypes/newsletter.md | 127 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 150 insertions(+) create mode 100644 archetypes/newsletter.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5deadeb..3624781 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -112,6 +112,29 @@ The `date` is provided here for example purposes only. Usually, you can leave it If not already present, a link should be added to the [site map](https://github.com/ivoa/ivoa-web/blob/main/layouts/partials/sitemap.html) pointing to the new page, or you may need to add one or more links to other parts of the site. Please consult with the site administrators if you have questions about where you might need to add or update links based on your changes. +## Adding a newsletter + +A newsletter is a content with a fairly similar structure from one newsletter to +another. In order to help creation of such content, it is possible to use a kind +of template (Hugo calls this an +[Archetype](https://gohugo.io/content-management/archetypes/)). +One exists for newsletters. + +To create a newsletter: + +1. (Optional) Ensure Hugo is locally installed (`make install`). + +2. Run the following command, where `XXX` is the number of the newsletter to + create (e.g. `026`): + + ```bash + ./hugo-bin/hugo new content newsletter/XXX.md + ``` + +3. Edit the file `content/newsletter/XXX.md`. There are content placeholders all + over this file ; search for all occurences of `TBD` and you will find them. + Just replace them by the content you would like to have. + # Pushing Changes to Github ## Committing and Pushing diff --git a/archetypes/newsletter.md b/archetypes/newsletter.md new file mode 100644 index 0000000..1490cd2 --- /dev/null +++ b/archetypes/newsletter.md @@ -0,0 +1,127 @@ +--- +date: '{{ .Date }}' +ideal_title: "IVOA Newsletter - { TBD - Date as 'Month Year' }" +tags: +- news +highlights: +- { TBD - One highlighted fact per line, prefixed as here with a '- ' } +--- + +[Subscribe](http://www.ivoa.net/mailman/listinfo/ivoa-news) | +[Newsletter archives](/newsletter/) | +[Write to the editors](mailto:ivoa-news-editors@ivoa.net) + +**The International Virtual Observatory Alliance (IVOA) was formed in June 2002 +with a mission to facilitate the international coordination and collaboration +necessary for the development and deployment of the tools, systems and +organizational structures necessary to enable the international utilization of +astronomical archives as an integrated and interoperating virtual observatory. +The IVOA now comprises 20 VO programs from Argentina, Armenia, Australia, +Brazil, Canada, Chile, China, Europe, France, Germany, Hungary, India, Italy, +Japan, Russia, South Africa, Spain, Ukraine, the United Kingdom, and the United +States and an inter-governmental organization (ESA). Membership is open to other +national and international programs according to the +[IVOA Guidelines for Participation](http://ivoa.net/Documents/latest/IVOAParticipation.html). +You can read more about the IVOA and what we do at +[http://ivoa.net/about/](/about/).** + +**What is the VO?** + +The Virtual Observatory (VO) aims to provide a research environment that will +open up new possibilities for scientific research based on data discovery, +efficient data access, and interoperability. The vision is of global astronomy +archives connected via the VO to form a multiwavelength digital sky that can be +searched, visualized, and analyzed in new and innovative ways. VO projects +worldwide working toward this vision are already providing science capabilities +with new tools and services. This newsletter, aimed at astronomers, highlights +VO tools and technologies for doing astronomy research, recent papers, and +upcoming events. + +--- + +# IVOA NEWS + + +{{< side-image image="" thumbnail="" position="left" floating="true" >}} + +### { TBD - TITLE } + +{ TBD - Comma-separated list of authors } + +{ TBD - Content } + +{{}} + +--- + +# Schools and workshops + +{{< side-image image="" thumbnail="" position="right" floating="true" >}} + +### { TBD - TITLE } + +{ TBD - Comma-separated list of "authors" } + +{ TBD - Content } + +{{}} + +--- + +# VO applications and implementation highlights + +{{< side-image image="" thumbnail="" position="left" floating="true" >}} + +### { TBD - TITLE } + +{ TBD - Comma-separated list of "authors" } + +{ TBD - Content } + +**More information:** { TBD - Links toward the application or related news } + +{{}} + +--- + +# Some recent papers about VO-enabled science + +### Featured Science Publication + +_{ TBD - Publication title }_ + +**{ TBD - Comma-separated list of authors }** + +_{ TBD - Where is it published? }_ + +{ TBD - Abstract } + +DOI: { TBD - DOI (e.g. [10.1093/mnras/stab1242](https://doi.org/10.1093/mnras/stab1242) ) } + +### [Refereed Publications](http://sdc.cab.inta-csic.es/vopubs/jsp/result.jsp?order=pub_id&bib=&com_id=-&com=&m_in=07&y_in=2020&m_en=01&y_en=2021&submit=Submit) { TBD - Check the parameters of this URL } + +The full list of refereed publications from { TBD - Date as "Month Year" } to { TBD - Date as "Month Year" } can be +found at the following +[list](https://sdc.cab.inta-csic.es/vopubs/jsp/result.jsp?order=cit_desc&bib=&com_id=-&com=&m_in=09&y_in=2021&m_en=03&y_en=2022&submit=Submit), +curated by the Spanish Virtual Observatory. + +### More Ways to Find VO-related Publications + +All [ADS links](https://ui.adsabs.harvard.edu/#search/q=abstract%3A%22Virtual%20Observatory%22&sort=date%20desc%2C%20bibcode%20desc) +mentioning the "virtual observatory" in the abstract. + +All [refereed publications](https://ui.adsabs.harvard.edu/#search/fq=%7B!type%3Daqp%20v%3D%24fq_property%7D&fq_property=(property%3A%22refereed%22)&q=abstract%3A%22Virtual%20Observatory%22&sort=date%20desc%2C%20bibcode%20desc) +mentioning the "virtual observatory" in the abstract. + +--- + +## VO calendar + +* **{ TBD - Date as: Day Month Year } - { TBD - Event name }** + + ({ TBD - Location (e.g. 'online', or a city and country) }) + + { TBD - Description } + + +{{< newsletter-social-links >}} \ No newline at end of file From ce8d5db8e0cd1d40001e4cbaadf749f23294187f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Mantelet?= Date: Fri, 29 Nov 2024 11:02:57 +0100 Subject: [PATCH 2/4] Move (and complete) instructions about newsletters in `NEWSLETTER.md` --- CONTRIBUTING.md | 23 ----------- NEWSLETTER.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+), 23 deletions(-) create mode 100644 NEWSLETTER.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3624781..5deadeb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -112,29 +112,6 @@ The `date` is provided here for example purposes only. Usually, you can leave it If not already present, a link should be added to the [site map](https://github.com/ivoa/ivoa-web/blob/main/layouts/partials/sitemap.html) pointing to the new page, or you may need to add one or more links to other parts of the site. Please consult with the site administrators if you have questions about where you might need to add or update links based on your changes. -## Adding a newsletter - -A newsletter is a content with a fairly similar structure from one newsletter to -another. In order to help creation of such content, it is possible to use a kind -of template (Hugo calls this an -[Archetype](https://gohugo.io/content-management/archetypes/)). -One exists for newsletters. - -To create a newsletter: - -1. (Optional) Ensure Hugo is locally installed (`make install`). - -2. Run the following command, where `XXX` is the number of the newsletter to - create (e.g. `026`): - - ```bash - ./hugo-bin/hugo new content newsletter/XXX.md - ``` - -3. Edit the file `content/newsletter/XXX.md`. There are content placeholders all - over this file ; search for all occurences of `TBD` and you will find them. - Just replace them by the content you would like to have. - # Pushing Changes to Github ## Committing and Pushing diff --git a/NEWSLETTER.md b/NEWSLETTER.md new file mode 100644 index 0000000..030e09f --- /dev/null +++ b/NEWSLETTER.md @@ -0,0 +1,104 @@ + +# How to create a newsletter? + +## Using a template + +A newsletter is a content with a fairly similar structure from one newsletter to +another. In order to help creation of such content, it is possible to use a kind +of template (Hugo calls this an +[Archetype](https://gohugo.io/content-management/archetypes/)). +One exists for newsletters (and can be modified when desired ; see next main +section ["How to edit the template?"](#how-to-create-a-newsletter)). + +To create a newsletter: + +1. (Optional) Ensure Hugo is locally installed (`make install`). + +2. Run the following command, where `XXX` is the number of the newsletter to + create (e.g. `026`): + + ```bash + ./hugo-bin/hugo new content newsletter/XXX.md + ``` + +3. Edit the file `content/newsletter/XXX.md`. There are content placeholders all + over this file ; search for all occurences of `TBD` and you will find them. + Just replace them by the content you would like to have. + +## Manual method + +1. Create a file called `XXX.md` (where `XXX` is the number of the newsletter to +create ; e.g. `026`) in the directory `content/newsletter/`. + +2. Starts with a header such as the following: + + ```md + --- + title: "IVOA Newsletter - November 2024" + date: 2024-11-01T10:58:36+02:00 + tags: + - news + highlights: + - ... + --- + ``` + +3. Then, just write the content of the newsletter. You can get inspired by the + previous newsletters available in the directory `content/newsletter/`. + +# How to edit the template? + +## The archetype itself + +The structure and content of the newsletters have already evolved few times in +the past. Such change is still possible in the future of the newsletters. When +it does, one has just to update the archetype itself: +[archetypes/newsletter.md](archetypes/newsletter.md) + +## The layout + +As special content, newsletters have a dedicated layout (called _template_ in +the Hugo documentation), or in other words, how the resulting HTML page is +rendered. If one wants to change this layout, there are two files to look at: + +- **[layouts/newsletter/list.html](layouts/newsletter/list.html):** layout for + the newsletters index page (aka ). + +- **[layouts/newsletter/single.html](layouts/newsletter/single.html):** layout + for a single newsletter. + +Layouts are written in HTML with some dynamic parts written with the Go +language. + +To get more information about Hugo layouts, take a look at the +[corresponding Hugo documentation](https://gohugo.io/templates/introduction/). +You can also look at the other layouts of this project in +[layouts/_default/](layouts/_default/) as working examples. + +This layout relies on CSS styles available in +[static/css/ivoa.css](static/css/ivoa.css) ; search for the styles with the +class `.newsletter`. + +## Social links + +Social links are inserted in the latest newsletters. This is done by adding the +following macro or snippet (called _shortcode_ by Hugo) in the desired +newsletter files: + +{{< highlight md >}} +{{}} +{{< /highlight >}} + +As the layout and the archetype, this may also be updated if necessary. One can +find the corresponding snippet in the file +[layouts/shortcodes/newsletter-social-links.html](layouts/shortcodes/newsletter-social-links.html). +As for layouts, this is a HTML snippet with dynamic parts written in Go. + +To get more information about Hugo shortcodes, take a look at the +[corresponding Hugo documentation](https://gohugo.io/templates/shortcode/). +You can also look at the other shortcodes available in this project in +[layouts/shortcodes/](layouts/shortcodes/) as working examples. + +This shortcode relies on CSS styles available in +[static/css/ivoa.css](static/css/ivoa.css) ; search for the section named +`SOCIAL LINKS`. Related images can be found in [static/images/](static/images/). \ No newline at end of file From 91b5fe50d7a337145554ecde3ad9d718af9cc64b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Mantelet?= Date: Fri, 29 Nov 2024 11:09:25 +0100 Subject: [PATCH 3/4] Fix the social link snippet in `NEWSLETTER.md` --- NEWSLETTER.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/NEWSLETTER.md b/NEWSLETTER.md index 030e09f..fe5cdf5 100644 --- a/NEWSLETTER.md +++ b/NEWSLETTER.md @@ -85,9 +85,9 @@ Social links are inserted in the latest newsletters. This is done by adding the following macro or snippet (called _shortcode_ by Hugo) in the desired newsletter files: -{{< highlight md >}} -{{}} -{{< /highlight >}} +```md +{{< newsletter-social-links >}} +``` As the layout and the archetype, this may also be updated if necessary. One can find the corresponding snippet in the file From bc27371e21c64db1c315be32df6da975ea53bffa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Mantelet?= Date: Tue, 3 Dec 2024 10:42:44 +0100 Subject: [PATCH 4/4] Add `make newsletter` --- Makefile | 21 ++++++++++++++++++++- NEWSLETTER.md | 19 ++++++++++++++++++- 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 1407ffb..f5ed851 100755 --- a/Makefile +++ b/Makefile @@ -23,13 +23,14 @@ DIR_PUBLIC_TMP=.public_tmp HUGO_CMD=${HUGO_DIR}/hugo -.PHONY: help preview update-search-index clear-search-index list-draft html generate-public-pages clear-generated-public-pages index-public-pages clear-public-pages-index clear install uninstall uninstall-hugo uninstall-pagefind +.PHONY: help preview update-search-index clear-search-index newsletter list-draft html generate-public-pages clear-generated-public-pages index-public-pages clear-public-pages-index clear install uninstall uninstall-hugo uninstall-pagefind #: Display this help (i.e. list all available targets). (DEFAULT TARGET) help: @echo "\nMake targets for ivoa-web:\n" @echo "* help Display help (default target).\n" @echo "* preview Start the preview service (on port 1313). All required tools\n are installed/upgraded automatically, when needed.\n" + @echo "* newsletter Create a new newsletter.\n" @echo "* html Generate the HTML version of the IVOA Website (with search\n index).\n" @echo "* list-draft List all draft pages (i.e. all pages only visible in preview\n mode).\n" @echo "* clear Delete local search index and generated public pages.\n" @@ -69,6 +70,24 @@ clear-search-index: rm -rf "${PAGEFIND_INDEX_DIR}"; \ fi +DIR_NEWSLETTER := content/newsletter +ID_LAST_NEWSLETTER := $(shell ls -1 $(DIR_NEWSLETTER) | grep '^[0-9]\+\.md$$' | sort -rn | head -n1 | sed 's/^0*\([1-9][0-9]*\)\.md$$/\1/' ) +NEXT_NEWSLETTER := $(shell printf "%03d.md" "$$(( $(ID_LAST_NEWSLETTER) + 1 ))") + +#: Create a new newsletter. +newsletter: install + @if ${HUGO_CMD} new content "newsletter/$(NEXT_NEWSLETTER)" ; \ + then \ + echo "(from the template 'archetypes/newsletter.md')" ; \ + echo "=> Next steps are yours:" ; \ + echo " 1. Edit the file '$(DIR_NEWSLETTER)/$(NEXT_NEWSLETTER)'" ; \ + echo " 2. Replace all occurences of 'TBD'" ; \ + echo " 3. Add any other content" ; \ + echo " 4. Commit and push changes" ; \ + else \ + echo "=> FAILED to create the newsletter '$(DIR_NEWSLETTER)/$(NEXT_NEWSLETTER)'!" ; \ + fi + #: List all draft pages (i.e. all pages only visible in preview mode). list-draft: install @echo diff --git a/NEWSLETTER.md b/NEWSLETTER.md index fe5cdf5..cdeb739 100644 --- a/NEWSLETTER.md +++ b/NEWSLETTER.md @@ -1,7 +1,7 @@ # How to create a newsletter? -## Using a template +## From template A newsletter is a content with a fairly similar structure from one newsletter to another. In order to help creation of such content, it is possible to use a kind @@ -10,6 +10,19 @@ of template (Hugo calls this an One exists for newsletters (and can be modified when desired ; see next main section ["How to edit the template?"](#how-to-create-a-newsletter)). +## Using the `make` command (recommended) + +1. Run the command `make newsletter` + +2. Edit the file returned by this command. There are content placeholders all + over this file ; search for all occurences of `TBD` and you will find them. + Just replace them by the content you would like to have. + +## Using the Hugo command + +This method is what the `make` command does behind the scene. These instructions +are given here for information and documentation. + To create a newsletter: 1. (Optional) Ensure Hugo is locally installed (`make install`). @@ -27,6 +40,10 @@ To create a newsletter: ## Manual method +This method is exactly what the Hugo command does behind the scene. Using this +method will make you create a newsletter completely from scratch. No template +will be used ; you will start from an empty file. + 1. Create a file called `XXX.md` (where `XXX` is the number of the newsletter to create ; e.g. `026`) in the directory `content/newsletter/`.