Skip to content

Latest commit

 

History

History
192 lines (142 loc) · 12 KB

README.md

File metadata and controls

192 lines (142 loc) · 12 KB

Instructions

This folder contains instructions for people new to coding, tips for cleaning markdown files imported from Google Docs, some old notes, and more details about building the application.

Table of Contents

First time coding

Starting may be daunting, but you can do it! Setting up will take some steps, but if you follow these in order it should be mostly surprise-free:

Setting up

Below steps need to be done only once:

  1. Install git
    • When installing, just click "next" through the default-selected options, no need to worry about any of them
    • This will automatically install Git Bash, a terminal for executing commands

Please read: Terminal is a tool you use to make your computer execute commands (anything formatted this way below is a command you run in your terminal). There are many terminals to choose from:

  • Mac: you can use the default terminal that comes with the OS
  • Windows: you can use Git Bash which is installed when you install git or Powershell that is part of the OS
    • or consider FluentTerminal or Tabby
    • if some installation below fails, you may need to try the command using Powershell
      • unlikely, but if you see an error about "administrator" something, try running Powershell as an administrator (right-click the icon in the Start menu and "Run as administrator")
  1. Install Hugo
    • Mac:
      • Install brew, then
      • brew install hugo
    • Windows:
      • Scoop (recommended)
        • Install Scoop, then
        • scoop install hugo-extended@0.143.0
      • Chocolatey (alternative)
        • Install Chocolatey, then
        • choco install hugo-extended --version=0.143.0
  2. Install Just
    • Mac: brew install just
    • Windows: scoop install just
  3. Install VSCode (step optional)
    • This is the nicest way to edit files
  4. Last steps 🎉 all in your terminal:
    • navigate to a folder where you would like your code to be located
      • this is done with the command cd followed by .. to go up a directory or a folder name to enter it
      • for example cd .., cd .. to go up twice, and then cd code to enter the folder with the name "code"
      • Windows: consider creating a folder C:\code to put all your code for ease of finding later
      • you can also use the tab key on your keyboard to auto-complete a folder name
    • clone this repository by running git clone https://github.com/whyboris/utilitarianism.net.git
    • enter the folder: cd utilitarianism.net

Developing

From now on any time you want to work on the website, with your terminal:

  1. enter the project folder (navigate to the folder utilitarianism.net on your computer with your terminal)
  2. run hugo serve with your terminal
  3. open http://localhost:1313/ in your browser (this link will appear in your terminal)

After editing any file (with VSCode or any other text editor) and saving it, the website will automatically refresh with the latest changes 🎉

Building

To build the website (generating all the files needed) we'll install just one more tool:

Only once:

  1. Install Node
  2. enter the project folder with your terminal
  3. run npm install1

Every time after:

Run npm run build in your terminal.

This should generate the search index, all the PDFs, and run a server to preview the final result. Additionally, this script puts the finished build into a zip file inside the dist folder to transfer to our webhost.

Feel free to reach out with questions by creating an Issue in this project's Issues page.

Importing from Google Docs

You can easily import Google Documents via Docs to Markdown (see documentation).

After adding a document it will likely need some manual fixes:

  • Update the metadata section (first few lines, see other files for reference)
  • If you install the MarkdownLint in your VSCode, you may save some time: right-click and "Format Document"
  • The article will likely have formatting errors with italics (underscores), so open the fixit.js file (in scripts folder), update the FILE_TO_FIX string, and execute: node fixit.js
    • note rather than jumping through below hoops, just use MarkdownLint (see instructions below)
    • note the fixit.js file is meant to be executed from the root of the repository (in / not in /archive where it resides) - so temporarily move it there if you use it.
    • it may be best to temporarily remove the Resources and Further Reading and Footnotes during this operation
    • alternatively you can render the HTML as is and Ctrl+F (find) _ on the page and manually update
  • Add the {{< TOC >}} to automatically generate the Table of Contents
  • Update the four spaces indentations to be > (quote)
  • Remove the "## How to cite" heading and replace the entire citation with {{< how-to-cite >}}
    • if the authors are not "MacAskill, W., Meissner, D., and Chappell, R.Y." then add authors: "author name(s)" to front matter (top of the file)
  • Add the Action button shortcode {{< button >}}
  • If a footnote was multi-paragraph, add the indentation so the text stays with the footnote (rather than being rendered to the page at the bottom)
  • Look over the document for any other manual fixes
  • Consider adding Code Spell Checker for catching some spelling mistakes.

Miscellaneous Notes

  • Consult Hugo documentation if you have trouble, or reach out to Boris with questions.
  • The description: field in the frontmatter (metadata at the top of most .md files) is used for the <meta name="description"> and is important for SEO (Search Engine Optimization)
  • We have a shortcode that will generate the table of contents: {{< TOC >}}
  • Front matter includes authors: which will be used in the "How to Cite This Page" section of each page.
    • if the field is absent, the default three authors will be listed
  • We enabled unsafe mode for Markdown to allow subscript and other HTML elements (e.g. see the glossary.md file)
  • Pages that have the same name as a folder need to be moved into the folder and renamed to _index.md to work properly (e.g. objections-to-utilitarianism)
    • these use the list.html layout
  • favicon is generated with this website
  • There is also a custom svg favicon to handle dark-theme browser, see instructions
  • site-header.html is unused - meant for homepage only (it may one day include a language dropdown)
  • In the future we may want to use some rtl support (try $.Site.Language.LanguageDirection "rtl")
  • We have used Prettier along with the prettier-plugin-go-template to format our code, but it creates some edits that need to then be manually reverted
    • To execute, run npm run prettier but please manually confirm that no errors snuck in.
      • One example is \_ after Animal Liberation book links - which breaks underlining (not what we want)
      • The . is moved to the next line in how to cite resulting in a space before the period
      • Some footnotes get indented incorrectly; even though the page and notes display correctly after, this isn't great
      • other minor things
    • The main benefit of having this installed, is that in VS Code you can right-click and format all the .html files now.

How builds are generated

  • PDF generation happens with website2pdf.
  • Search is handlede with pagefind
    • If npm install errors out on Windows, consider using the PowerShell terminal instead
    • It is build with just search and is part of the just build command, no manual steps needed
    • During the build, to add image previews to the side of search results, search = true is toggled in config.toml
    • Durning the build, hugo runs in parallel with pagefind --site public which creates the pagefind folder inside /public
  • If you run hugo and see the warning "port 1313 already in use, attempting to use an available port" try npm run kill-hugo which is equivalent to npx kill-port 1313

When you run the npm run build script, under the hood we'll use just to execute these in order:

  • Clean the /public folder
  • Build the Search index
  • Build the PDF files
  • Build the final website
  • Zip the /public directory into a single file in /dist
  • Serve the /public folder for a quick manual check

See justfile for details; notice it uses build.js to do some of its bidding.

Once the build is finished, you'll get a link in your terminal (to http://localhost:3000) which will be a local preview of the finished website. Please spot-check it to make sure it functions as expected (for example: search works & PDFs exist).

Languages / Translations

All languages are accessible during development, each has its own link when you run npm start. When you are ready to build the public website (with all the search & PDF capabilities) in a particular language, run the associated command:

  • English: just build
  • German: just build-de
  • Spanish: just build-es

Note: PDF filenames in German have some replacements: ü -> ue, ß -> ss, ä -> a, ó -> o, É -> E, é -> e, í -> i, á -> a; while “ & „ are removed -- all so that PDFs are accessible when the link is clicked. See move-pdf.js and PDF.html (both of which need identical replacement rules).

Audio

Until the audio is ready and set up, we can set hideAudio to be true in config.toml

    [languages.es.params]
      hideAudio = true

Bibliography

For our Spanish version of the website, we generate citations with hugo-cite automatically, but we need the bib file:

Copy stable.bib to your computer and use pandoc to convert stable.bib to bib.json with this command:

pandoc stable.bib -t csljson -o bib.json

Place the file in /assets, and run npm run fix-bib which will generate bib2.json for easier use by our system.

We used the code from hugo-cite. Just these two files were copied from the above repository and cite.html was modified heavily for our use case:

  • layouts/shortcodes/cite.html
  • layouts/partials/bibliography/apa-style.html

Citations originally came from TLON as [@Singer1972]; we can search and replace \[@(.+?)\] RegEx with {{< cite $1 >}} and then fix any page references (e.g. after the citation shortcode include any string "chap. 3")

Footnotes

  1. If you see an error while Pagefind is being installed, something like Error: tar xvf exited with 128 try using Powershell when running npm install ↩