Merge pull request #41 from mapachurro/readme-rectify

README: align some information from old version, move lots of detail elsewhere

Author: mapachurro

.github/ISSUE_TEMPLATE/term_request.md

@@ -1,5 +1,5 @@
 ---
-name: 1. Term Addition/Modification
+name: 1. Term addition or modification
 about: Suggest a new term or modify an existing one
 title: '[TERM] - '
 labels: content

.github/legacy/template-backup.md

@@ -0,0 +1,45 @@
+---
+name: 'Add or modify a term '
+about: 'Make a suggestion to add or improve a term''s entry '
+title: "[SUBMISSION]"
+labels: ''
+assignees: ''
+
+---
+
+You can make your suggestion in writing, ie "narrative" form here, like: 
+
+"We should add the term 'stonks' because everybody in Discord says it. The definition should be "A meme meaning the value of something is good. Or bad."
+
+Or you can submit an entry using the JSON format in which each term record is saved: 
+
+```
+    "0x-api": {
+      "term": "0x API",
+      "partOfSpeech": "noun",
+      "termCategory": "",
+      "phonetic": "/ˌzɪroʊ ˈɛks ˈeɪ.pi.aɪ/",
+      "definition": "The 0x API is the liquidity and data endpoint for DeFi. It lets you access aggregated liquidity from tens of on-chain and off-chain decentralized exchange networks, across multiple blockchains. It comes with many parameters to customize your requests for your application and your users.",
+      "definitionSource": "",
+      "sampleSentence": "",
+      "extended": "",
+      "termSource": "",
+      "dateFirstRecorded": "",
+      "commentary": ""
+    },
+
+```
+
+    "0x-api": { `this is a sanitized version of the term, that will appear as a URL`
+      "term": "0x API", `this is the term itself`
+      "partOfSpeech": "noun", `what grammatical category is it?`
+      "termCategory": "", `is it web3? Web2? Memes?`
+      "phonetic": "/ˌzɪroʊ ˈɛks ˈeɪ.pi.aɪ/", `an IPA pronunciation`
+      "definition": "The 0x API is the liquidity and data endpoint for DeFi. It lets you access aggregated liquidity from tens of on-chain and off-chain decentralized exchange networks, across multiple blockchains. It comes with many parameters to customize your requests for your application and your users.", `The definition of the term. This should be one to two sentences, and don't use the term in its own definition.`
+      "definitionSource": "", `Who wrote this definition?`
+      "sampleSentence": "", `Can you use it in a sentence?`
+      "extended": "", `Is there more to say? Back story? Multiple uses? Debate?`
+      "termSource": "", `Know who coined the term? Did it come from a specific website or account?`
+      "dateFirstRecorded": "", `Date of submission here`
+      "commentary": "" `If there is active debate, room for doubt, a topic under development, this is the place for explanations!`
+    },

.github/workflows/deploy.yml

@@ -0,0 +1,57 @@
+name: Deploy to GH Pages
+
+on:
+  push:
+    branches:
+      - main # Replace with your branch name if different
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    # Step 1: Checkout the repository
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    # Step 2: Set up Node.js
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 21
+
+    # Step 3: Install dependencies and build the project
+    - name: Install dependencies and buildg
+      run: |
+        npm ci
+        npm run build
+
+    # upload as artifact
+    - name: Upload static files as artifact
+      id: deployment
+      uses: actions/upload-pages-artifact@v3 # or specific "vX.X.X" version tag for this action
+      with:
+        path: ./build
+
+
+  # Deploy job
+  deploy:
+    # Add a dependency to the build job
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this action

README.md

@@ -9,25 +9,57 @@ A multilingual glossary for web3, crypto, and decentralized web terminology, dep
 
 ## Overview
 
-wordsofweb3 is a collaborative project by [Education DAO](https://educationdao.xyz/) that aims to create a credibly neutral, living record of web3 terminology. The project supports multiple languages and provides an intertextual experience where terms link to related concepts.
+wordsofweb3 is a collaborative project by [Education DAO](https://educationdao.xyz/) that aims to create a credibly neutral, living record of web3 and decentralized web tech terminology. 
+
+The project supports multiple languages and provides an intertextual experience where terms link to related concepts.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Design Philosophy](#design-philosophy)
+- [Features](#features)
+- [Supported Languages](#supported-languages)
+- [Getting Started](#getting-started)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+  - [Technical Conventions](#technical-conventions)
+- [Project Architecture](#project-architecture)
+  - [Directory Structure](#directory-structure)
+  - [Data Management](#data-management)
+    - [CSV Files](#csv-files)
+    - [Build Process](#build-process)
+- [Search Functionality](#search-functionality)
+- [Visual Identity](#visual-identity)
+  - [Color Palette](#color-palette)
+- [Contributing](#contributing)
+- [Development](#development)
+  - [Building the Project](#building-the-project)
+  - [Testing](#testing)
+    - [Test on local server](#test-on-local-server)
+- [Deployment](#deployment)
+- [Future Plans](#future-plans)
+- [License](#license)
+- [Contact](#contact)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Design Philosophy
 
 This app is meant to be _for the ages_. We follow these core principles:
 
-- **Longevity**: Built to sometimes break(but never fail, like every other durable thing out there), using the simplest possible solutions
+- **Longevity**: Built to sometimes break (but never fail, like every other durable thing out there), using the simplest possible solutions
 - **Accessibility**: Available to the widest possible audience
 - **Decentralization**: Deployed on [IPFS](https://ipfs.tech/) for permanent availability
 - **Simplicity**: Minimal dependencies, custom solutions over external packages
-- **Language Neutrality**: Working towards a language-agnostic approach
+- **Language neutrality**: Working towards a human language-agnostic design.
 
 ## Features
 
-- **Multilingual Support**: Available in 28+ languages
-- **Intertextual Experience**: Terms link to related concepts within definitions
-- **Search Functionality**: Easy term lookup across all supported languages
-- **Static Generation**: All pages built at compile time for reliability
-- **Decentralized Storage**: Deployed on IPFS via [Fleek]((https://fleek.xyz/))
+- **Multilingual support**: Available in 28+ languages
+- **Intertextual experience**: Terms link to related concepts within definitions
+- **Search functionality**: Easy term lookup across all supported languages
+- **Static generation**: All pages built at compile time for reliability
+- **Decentralized storage**: Deployed on IPFS via [Fleek]((https://fleek.xyz/)); working towards multiple fallbacks, e.g. Arweave, GH Pages, etc.
 
 ## Supported Languages
 
@@ -42,11 +74,27 @@ This app is meant to be _for the ages_. We follow these core principles:
 - Français (French)
 - Deutsch (German)
 - Eλληνικά (Greek)
+- Hausa
 - हिन्दी (Hindi)
 - 日本語 (Japanese)
 - 한국어 (Korean)
-- Español (Latin America)
-- And many more...
+- Español de (Latin America)
+- Magyar (Hungarian)
+- Bahasa Indonesia (Indonesian)
+- Italiano (Italian)
+- فارسی (Persian)
+- Bahasa Melayu (Malaysian)
+- Pidgin (Nigerian Pidgin)
+- Polski (Polish)
+- Português Brasileiro (Brazilian Portuguese)
+- Limba Română (Romanian)
+- Русские (Russian)
+- Español de América Latina (Latin American Spanish)
+- Tagalog (Filipino)
+- ไทย (Thai)
+- Türkçe (Turkish)
+- Українська (Ukrainian)
+- Tiếng-việt (Vietnamese)
 
 </details>
 
@@ -63,14 +111,21 @@ This app is meant to be _for the ages_. We follow these core principles:
 bash
 git clone https://github.com/mapachurro/wordsofweb3.git
 cd wordsofweb3
+nvm use
+```
+If necessary, based on console output, run `nvm install`
+
+Once the correct version of node is installed, run:
+
+```bash
 npm install
 ```
 
 ### Technical Conventions
 
 1. **Module System**
    - Use ES Module syntax throughout
-   - No CommonJS `require()` statements
+    - No CommonJS `require()` statements
 
 2. **Error Handling**
    - Include graceful failures
@@ -81,6 +136,8 @@ npm install
    - Prefer custom scripts over npm packages
    - Maintain minimal dependencies
 
+**Note**: *Currently, this project does not bundle any JS into the client side. It outputs static JS files for specific pages only.*
+
 ## Project Architecture
 
 ### Directory Structure
@@ -109,6 +166,8 @@ npm install
 3. Intertextual links created
 4. Search indices built
 
+See [the build script](./utils/build.js) for more detail.
+
 ## Search Functionality
 
 The search system provides:
@@ -118,6 +177,9 @@ The search system provides:
 - Partial matches
 - Language-specific search indices
 
+The search results are drawn from indices made during the build process.
+They will be located in each locale's built directory, under the file name `directoryContents.json`.
+
 ## Visual Identity
 
 ### Color Palette
@@ -148,28 +210,41 @@ We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for:
 npm run build
 ```
 
-
 This will:
 1. Generate homepages
 2. Build term pages
 3. Create intertextual links
 4. Generate search indices
 5. Copy static assets
 
+For a detailed, if not always up to date, walkthrough of data importation and site build processes, see [the build README](./utils/BUILD-README.md).
+
 ### Testing
 
 Before deployment:
 
-1. Test on local server
+1. [Test on local server](#test-on-local-server)
 2. Verify language switching
 3. Check search functionality
 4. Validate intertextual links
 
+#### Test on local server
+
+Once you've installed this project, you can simply run:
+
+```bash
+- npm run build
+- npm run start
+```
+and you will have the site running locally at `localhost:8080`.
+
 ## Deployment
 
-- Primary: IPFS via Fleek.xyz
-- ENS: wordsofweb3.eth
-- Access: wordsofweb3.eth.limo
+The site is currently deployed using a combination of two web3 technologies:
+
+- Site builds uploaded to IPFS, and domain routed to that content hash, via [Fleek](https://fleek.xyz)
+- [ENS](https://ens.domains) is used to create  the `wordsofweb3.eth` name
+- ENS' 'limo' routing service integrates with Fleek to allow the site to **be accessible at [wordsofweb3.eth.limo](https://wordsofweb3.eth.limo)**.
 
 ## Future Plans