Merge pull request #104 from ivoa/add-newsletter-archetype

Add a newsletter Archetype

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

NEWSLETTER.md

@@ -0,0 +1,121 @@
+
+# How to create a newsletter?
+
+## 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
+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)).
+
+## 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`).
+
+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
+
+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/`.
+
+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 <https://ivoa.net/newsletter/>).
+
+- **[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:
+
+```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
+[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/).

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:[email protected])
+
+**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 }
+
+{{</ side-image >}}
+
+---
+
+# Schools and workshops
+
+{{< side-image image="" thumbnail="" position="right" floating="true" >}}
+
+### { TBD - TITLE }
+
+{ TBD - Comma-separated list of "authors" }
+
+{ TBD - Content }
+
+{{</ side-image >}}
+
+---
+
+# 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 }
+
+{{</ side-image >}}
+
+---
+
+# 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 >}}