diff --git a/README.md b/README.md index 03b7599a4..796a6aac2 100644 --- a/README.md +++ b/README.md @@ -185,17 +185,13 @@ Use the included `new_contribs.sh` script: ## Building -To ensure consistency across development setups, we use a -[Docker](https://www.docker.com) container-based workflow for building the -website and email newsletter. Similarly, we use [Just](https://just.systems/) to -ensure you have Docker installed on your system if you intend to build the -website or email newsletter. +To ensure consistency across development setups, we use a container-based workflow for building the website and email newsletter. [Docker](https://www.docker.com) is used by default, but you can use any drop-in Docker replacement, such as [Podman](https://podman.io/). + +Similarly, we use [Just](https://just.systems/) to ensure you have Docker or a suitable alternative installed on your system, as well as to run the various commands necessary to build the website or email newsletter. ### Install Just -To install Just you have -[many options](https://just.systems/man/en/packages.html); we recommend using -Cargo: +To install Just you have [many options](https://just.systems/man/en/packages.html); we recommend using Cargo: ```sh cargo install just @@ -205,8 +201,7 @@ cargo install just > [!IMPORTANT] > -> Before attempting to build the website, ensure Docker is in a running state on -> your system. +> Before attempting to build the website, ensure Docker or a suitable alternative is running on your system. - Enter the `publishing/` directory: @@ -220,23 +215,23 @@ cd publishing just website ``` -- View the website locally at default - [http://localhost:8000](http://localhost:8000), or specific posts at - `http://localhost:8000/blog/{YEAR}/{MONTH}/{DAY}/{ISSUE}/` +- To use a container engine besides Docker, append the appropriate command at the end: + +```sh +just website podman +``` + +- View the website locally at default , or specific posts at `http://localhost:8000/blog/{YEAR}/{MONTH}/{DAY}/{ISSUE}/` > [!NOTE] > -> If looking to test the website's search functionality locally, you will need -> to adjust the -> [`TESTING_LOCALLY`](https://github.com/rust-lang/this-week-in-rust/blob/dc127f17fcabbf0f058eb3d5a3febba434ddca83/pelicanconf.py#L7) -> variable to `True`. +> If looking to test the website's internal links locally, you will need to adjust the [`TESTING_LOCALLY`](https://github.com/rust-lang/this-week-in-rust/blob/dc127f17fcabbf0f058eb3d5a3febba434ddca83/pelicanconf.py#L7) variable to `True`. ### Building the newsletter > [!IMPORTANT] > -> Before attempting to build the website, ensure Docker is in a running state on -> your system. +> Before attempting to build the newsletter, ensure Docker or a suitable alternative is running on your system. - Enter the `publishing/` directory: @@ -244,11 +239,16 @@ just website cd publishing ``` -- Run the Docker build and website local-host command: +- Run the Docker build and newsletter generation command: ```sh just email ``` -- View the email newsletter formatting of specific posts at - `http://localhost:8000/blog/{YEAR}/{MONTH}/{DAY}/{ISSUE}/` +- To use a container engine besides Docker, append the appropriate command at the end: + +```sh +just email podman +``` + +- View the email newsletter formatting of most recent issue at `publishing/email/{ISSUE}.html`, or view the formatting of a specific issue at `publishing/output-email-format/blog/{YEAR}/{MONTH}/{DAY}/{ISSUE}/index.html`. diff --git a/publishing/create_optimized_email.sh b/publishing/create_optimized_email.sh deleted file mode 100755 index 12a346fca..000000000 --- a/publishing/create_optimized_email.sh +++ /dev/null @@ -1,28 +0,0 @@ -#!/bin/bash - -source utils.sh - -LOCAL_EMAIL_PREFIX="email/${LATEST_ISSUE_NUMBER}-${LATEST_YEAR}-${LATEST_MONTH}-${LATEST_DAY}" -echo "Creating email for ${LATEST_ISSUE_NUMBER}-${LATEST_YEAR}-${LATEST_MONTH}-${LATEST_DAY}" - -# Prepare email directory -mkdir -p email -rm -f ${LOCAL_EMAIL_PREFIX}-in.html -cp ${LATEST_ISSUE_FULL_PATH} ${LOCAL_EMAIL_PREFIX}-in.html - -docker run \ - -v $(pwd)/email:/usr/twir/email \ - -e LOCAL_EMAIL_PREFIX=${LOCAL_EMAIL_PREFIX} \ - twir:latest \ - bash create_html_friendly_page.sh - -rm ${LOCAL_EMAIL_PREFIX}-in.html - -printf "\n\n${CYAN_FONT}*****${PURPLE_FONT}*****${CYAN_FONT}*****${PURPLE_FONT}*****${NC}" -printf "\n${CYAN_FONT}*****${PURPLE_FONT}*****${CYAN_FONT}*****${PURPLE_FONT}*****${NC}" -printf "\n${CYAN_FONT}*****${PURPLE_FONT}*****${CYAN_FONT}*****${PURPLE_FONT}*****${NC}" -printf "\n📧 HEY TWiR PUBLISHER..." -printf "\nLatest email template found at: ${YELLOW_FONT}'$(pwd)/${LOCAL_EMAIL_PREFIX}-email.html'${NC}" -printf "\n${CYAN_FONT}*****${PURPLE_FONT}*****${CYAN_FONT}*****${PURPLE_FONT}*****${NC}" -printf "\n${CYAN_FONT}*****${PURPLE_FONT}*****${CYAN_FONT}*****${PURPLE_FONT}*****${NC}" -printf "\n${CYAN_FONT}*****${PURPLE_FONT}*****${CYAN_FONT}*****${PURPLE_FONT}*****${NC}\n\n" diff --git a/publishing/justfile b/publishing/justfile index 030228194..3dd490ddb 100644 --- a/publishing/justfile +++ b/publishing/justfile @@ -36,19 +36,23 @@ help: # Output: `email/----email.html` # +set unstable + +default-container-engine := "docker" + # Generate and host website locally -website: generate-website host-website +website container-engine=default-container-engine: (generate-website container-engine) (host-website container-engine) # Copy website contents to this-week-in-rust.github.io repo copy-website-contents: ./copy_website_content_to_repo.sh # Generate and optimize email template -email: generate-email optimize-email +email container-engine=default-container-engine: (generate-email container-engine) (optimize-email container-engine) -# Build Docker image -docker-build: - cd .. && docker build -t twir -f publishing/Dockerfile . && cd - +# Build container engine image (Docker by default) +container-build container-engine=default-container-engine: + cd .. && {{container-engine}} build -t twir -f publishing/Dockerfile . && cd - # Clean website output directories clean-website: @@ -59,17 +63,18 @@ clean-email: rm -rf output/ output-email-format/ email/ juice/ # Generate website content -generate-website: docker-build clean-website +generate-website container-engine=default-container-engine: (container-build container-engine) clean-website @echo "Generating website..." - docker run -it \ + mkdir -p output-website + {{container-engine}} run -it \ -v {{justfile_directory()}}/output-website:/usr/twir/output \ twir:latest @echo "Finished generating website." # Host website locally on port 8000 -host-website: +host-website container-engine=default-container-engine: @echo "Hosting website..." - docker run -it \ + {{container-engine}} run -it \ -p 8000:8000 \ -v {{justfile_directory()}}/output-website:/usr/twir/output:ro \ -it \ @@ -80,15 +85,43 @@ host-website: @echo "To sync contents with your local 'this-week-in-rust.github.io' repo, run 'just copy-website-contents'" # Generate email content -generate-email: docker-build clean-email +generate-email container-engine=default-container-engine: (container-build container-engine) clean-email @echo "Generating email..." mkdir -p output-email-format - docker run -it \ + {{container-engine}} run -it \ -e USE_EMAIL_THEME=1 \ -v {{justfile_directory()}}/output-email-format:/usr/twir/output \ twir:latest # Optimize email HTML for delivery -optimize-email: - @echo "Generating optimized email..." - OUTPUT_PREFIX=output-email-format ./create_optimized_email.sh +[script("bash")] +optimize-email container-engine=default-container-engine: + echo "Generating optimized email..." + OUTPUT_PREFIX="output-email-format" + + source utils.sh + + LOCAL_EMAIL_PREFIX="email/${LATEST_ISSUE_NUMBER}-${LATEST_YEAR}-${LATEST_MONTH}-${LATEST_DAY}" + echo "Creating email for ${LATEST_ISSUE_NUMBER}-${LATEST_YEAR}-${LATEST_MONTH}-${LATEST_DAY}" + + # Prepare email directory + mkdir -p email + rm -f ${LOCAL_EMAIL_PREFIX}-in.html + cp ${LATEST_ISSUE_FULL_PATH} ${LOCAL_EMAIL_PREFIX}-in.html + + {{container-engine}} run \ + -v $(pwd)/email:/usr/twir/email \ + -e LOCAL_EMAIL_PREFIX=${LOCAL_EMAIL_PREFIX} \ + twir:latest \ + bash create_html_friendly_page.sh + + rm ${LOCAL_EMAIL_PREFIX}-in.html + + printf "\n\n${CYAN_FONT}*****${PURPLE_FONT}*****${CYAN_FONT}*****${PURPLE_FONT}*****${NC}" + printf "\n${CYAN_FONT}*****${PURPLE_FONT}*****${CYAN_FONT}*****${PURPLE_FONT}*****${NC}" + printf "\n${CYAN_FONT}*****${PURPLE_FONT}*****${CYAN_FONT}*****${PURPLE_FONT}*****${NC}" + printf "\n📧 HEY TWiR PUBLISHER..." + printf "\nLatest email template found at: ${YELLOW_FONT}'$(pwd)/${LOCAL_EMAIL_PREFIX}-email.html'${NC}" + printf "\n${CYAN_FONT}*****${PURPLE_FONT}*****${CYAN_FONT}*****${PURPLE_FONT}*****${NC}" + printf "\n${CYAN_FONT}*****${PURPLE_FONT}*****${CYAN_FONT}*****${PURPLE_FONT}*****${NC}" + printf "\n${CYAN_FONT}*****${PURPLE_FONT}*****${CYAN_FONT}*****${PURPLE_FONT}*****${NC}\n\n"