### Paranext Walkthroughs and Guides

Source: https://github.com/paranext/paranext-core/wiki/Platform.Bible-and-Paratext-10-Studio

Guides for getting started with Platform.Bible and Paratext 10 Studio, building the project, and creating extensions, including video walkthroughs.

```GitHub Wiki
https://github.com/paranext/paranext/wiki/Getting-Started-with-Platform.Bible-and-Paratext-10-Studio
```

```GitHub
https://github.com/paranext/paranext-core?tab=readme-ov-file#developer-install
```

```GitHub Wiki
https://github.com/paranext/paranext-extension-template/wiki/Your-First-Extension
```

```Google Drive
https://drive.google.com/file/d/12F6XpNu9cjtF9Z6Phe-7GuWWlearcw27/view?t=50m57s
```

```Google Docs
https://docs.google.com/document/d/1KBvnmwTxaO5h4Rq8PV82v2GELNslyVKCbFJ1-FV3TVQ
```

```Google Drive
https://drive.google.com/file/d/17CM4PlL_OikCP1lvBlAp01nDoAJnPoYw/view
```

--------------------------------

### Install and Setup Extension Template

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-rock3/README.md

Instructions for installing and setting up the Platform.Bible extension template. This involves cloning the repository and potentially running installation commands.

```bash
# To install and set up this repo
# (Skip if creating an extension within paranext-multi-extension-template)
# Further instructions would typically follow here, like running npm install or similar.
```

--------------------------------

### Install Dependencies

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-rock3/README.md

Commands to install project dependencies and potentially setup the paranext-core dependency.

```bash
# Install paranext-core (assuming it's cloned in a parent directory)
git clone https://github.com/paranext/paranext-core.git ../paranext-core

# Install local dependencies
npm install
```

--------------------------------

### Install Dependencies

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-someone/README.md

Commands to install project dependencies and potentially setup the paranext-core dependency.

```bash
# Install paranext-core (assuming it's cloned in a parent directory)
git clone https://github.com/paranext/paranext-core.git ../paranext-core

# Install local dependencies
npm install
```

--------------------------------

### Install and Set Up Repo

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-get-resources/README.md

Instructions for installing and setting up the repository. This typically involves cloning the repository and installing dependencies.

```bash
git clone <repository-url>
cd <repository-name>
npm install
```

--------------------------------

### Install and Set Up Repository

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-lexical-tools/README.md

Instructions for installing and setting up the repository. This is a prerequisite for customizing the template and hooking it up for future updates.

```bash
#!/bin/bash

# Install dependencies
npm install

# Build the project
npm run build
```

--------------------------------

### Install and Set Up Repository

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/quick-verse/README.md

Instructions for installing and setting up the repository. This is a prerequisite for customizing the template.

```bash
# Install dependencies
npm install

# Build the extension
npm run build
```

--------------------------------

### Install Dependencies

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-scripture-editor/README.md

Commands to install project dependencies and potentially setup the paranext-core dependency.

```bash
# Install paranext-core (assuming it's cloned in a parent directory)
git clone https://github.com/paranext/paranext-core.git ../paranext-core

# Install local dependencies
npm install
```

--------------------------------

### Install Dependencies

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/quick-verse/README.md

Installs local and published dependencies for the extension. Requires prior installation of paranext-core.

```bash
npm install
```

--------------------------------

### Install and Set Up Repository

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-scripture-editor/README.md

Instructions for installing and setting up the repository. This is a prerequisite for customizing the template.

```bash
# To install
# (Specific commands would go here if provided in the text)
```

--------------------------------

### Install and Set Up Repo

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/legacy-comment-manager/README.md

Instructions for installing and setting up the current repository. This is a prerequisite for customizing the template.

```bash
#!/bin/bash

# Example installation command (replace with actual commands)
# npm install
# npm run build
```

--------------------------------

### Install Dependencies

Source: https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-utils/README.md

Installs the necessary dependencies for the development environment.

```bash
npm i
```

--------------------------------

### Install Local Snap Package

Source: https://github.com/paranext/paranext-core/blob/main/README.md

Commands to install a locally created snap package for Platform.Bible on Linux. It includes installing the snap file and connecting it to the dot-platform-bible interface.

```bash
sudo snap install <path to snap file> --dangerous
sudo snap connect platform-bible:dot-platform-bible
```

--------------------------------

### Install Dependencies

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-lexical-tools/README.md

Installs local and published dependencies for the extension. Requires prior installation of paranext-core.

```bash
npm install
```

--------------------------------

### Paranext Development Guides

Source: https://github.com/paranext/paranext-core/wiki/Platform.Bible-and-Paratext-10-Studio

Guides for developers on code style, code review, testing, UX design, and a project glossary.

```GitHub Wiki
https://github.com/paranext/paranext/wiki/Code-Style-Guide
```

```GitHub Wiki
https://github.com/paranext/paranext/wiki/Code-Review-Guide
```

```GitHub Wiki
https://github.com/paranext/paranext/wiki/Testing-Guide
```

```GitHub Wiki
https://github.com/paranext/paranext/wiki/Design-System
```

```Notion
https://www.notion.so/paratext/6ca2c1d0e4f34713a883cc07902c0b9e?v=5a8a02f436b143e0883b28ef98faabda
```

--------------------------------

### Start Platform.Bible with Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/quick-verse/README.md

Starts Platform.Bible with the extension. The built extension is located in the 'dist' folder and is automatically referenced via a command-line argument in the package.json start script.

```bash
npm start
```

--------------------------------

### Install Dependencies

Source: https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/README.md

Installs all necessary dependencies for the development environment.

```bash
npm i
```

--------------------------------

### Run Preview Site

Source: https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/preview/README.md

Starts the local development server for the preview site, enabling live reloading of platform-bible-react components.

```bash
npm start
```

--------------------------------

### Start Platform.Bible with Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-lexical-tools/README.md

Starts Platform.Bible with the extension. The built extension is located in the 'dist' folder and is automatically provided via a command-line argument in the package.json start script.

```bash
npm start
```

--------------------------------

### Running the Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-someone/README.md

Command to start Platform.Bible with the Paranext Core extension. It highlights the need to specify the extension path.

```bash
# Start Platform.Bible with the extension
npm start
```

--------------------------------

### Start Platform.Bible with Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/legacy-comment-manager/README.md

Starts Platform.Bible with the extension. The built extension is located in the 'dist' folder and is automatically provided via a command-line argument in the package.json 'start' script.

```bash
npm start
```

--------------------------------

### Running the Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-rock3/README.md

Command to start Platform.Bible with the Paranext Core extension. It highlights the need to specify the extension path.

```bash
# Start Platform.Bible with the extension
npm start
```

--------------------------------

### Install Dependencies

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-get-resources/README.md

Installs local and published dependencies for the extension. Requires prior installation of paranext-core.

```bash
npm install
```

--------------------------------

### Install Dependencies

Source: https://github.com/paranext/paranext-core/blob/main/extensions/README.md

Installs project dependencies using npm. This includes installing local and published dependencies for the extensions.

```bash
npm install
```

--------------------------------

### Installing Dependencies and Building Paranext Core

Source: https://github.com/paranext/paranext-core/blob/main/README.md

Installs project dependencies using npm and then builds the project. These are standard commands for Node.js projects managed with npm.

```bash
npm install
npm run build
```

--------------------------------

### Starting Paranext Core Development Server

Source: https://github.com/paranext/paranext-core/blob/main/README.md

Starts the Paranext application in the development environment. This command also enables hot reloading for code changes during development.

```bash
npm start
```

--------------------------------

### Install Dependencies

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/paratext-registration/README.md

Installs local and published dependencies for the extension. Assumes paranext-core is installed.

```bash
npm install
```

--------------------------------

### Setup WebView event handlers and data subscriptions

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-someone/src/hello-someone.web-view.html

Sets up event listeners for buttons to interact with a people data provider. Includes handlers for getting greetings, deleting people, setting greetings, and setting ages. Also subscribes to people and greeting updates to update the UI.

```javascript
const papi = require('@papi/frontend');
const { logger } = require('@papi/frontend');
const { getErrorMessage, htmlEncode, isPlatformError, serialize, } = require('platform-bible-utils');
function print(input) { logger.debug(input); }
const dataProviderPromise = papi.dataProviders.get('helloSomeone.people');
async function setupWebView() {
  const peopleDataProvider = await dataProviderPromise;
  // Attach handler for greetings-button
  const greetingsButton = document.getElementById('greetings-button');
  greetingsButton.addEventListener('click', async () => {
    const nameInput = document.getElementById('name-input');
    const greeting = await peopleDataProvider.getGreeting(nameInput.value.toLowerCase());
    const helloSomeoneOutput = document.getElementById('greetings-button-output');
    helloSomeoneOutput.textContent = htmlEncode(greeting || '');
    print(greeting);
  });
  greetingsButton.addEventListener('contextmenu', async (e) => {
    e.preventDefault();
    const nameInput = document.getElementById('name-input');
    const name = nameInput.value.toLowerCase();
    const promises = new Array(10000);
    for (let i = 0; i < 10000; i += 1)
      promises[i] = peopleDataProvider.getGreeting(name);
    await Promise.all(promises);
    print('Done');
  });
  // Attach handler for delete-button
  const deleteButton = document.getElementById('delete-button');
  deleteButton.addEventListener('click', async () => {
    const nameInput = document.getElementById('name-input');
    const success = await peopleDataProvider.deletePerson(nameInput.value.toLowerCase());
    const helloSomeoneOutput = document.getElementById('greetings-button-output');
    helloSomeoneOutput.textContent = htmlEncode(
      `${success ? 'Successfully' : 'Unsuccessfully'} deleted ${nameInput.value}.${
        success ? ' RIP ⚰️' : ''
      }`.replace(/'/g, '`'),
    );
  });
  // Attach handler for set-greetings-button
  const setGreetingsButton = document.getElementById('set-greetings-button');
  setGreetingsButton.addEventListener('click', async () => {
    const nameInput = document.getElementById('name-input');
    const name = nameInput.value;
    const setGreetingsInput = document.getElementById('set-greetings-input');
    const success = await peopleDataProvider.setGreeting(
      name.toLowerCase(),
      setGreetingsInput.value,
    );
    const helloSomeoneOutput = document.getElementById('greetings-button-output');
    helloSomeoneOutput.textContent = htmlEncode(
      `${success ? 'Successfully' : 'Unsuccessfully'} set ${name}'s greeting!`.replace(
        /'/g, '`',
      ),
    );
  });
  // Attach handler for set-age-button
  const setAgeButton = document.getElementById('set-age-button');
  setAgeButton.addEventListener('click', async () => {
    const nameInput = document.getElementById('name-input');
    const name = nameInput.value;
    const setAgeInput = document.getElementById('set-age-input');
    const success = await peopleDataProvider.setAge(
      name.toLowerCase(),
      parseInt(setAgeInput.value),
    );
    const helloSomeoneOutput = document.getElementById('greetings-button-output');
    helloSomeoneOutput.textContent = htmlEncode(
      `${success ? 'Successfully' : 'Unsuccessfully'} set ${name}'s age!`.replace(/'/g, '`'),
    );
  });
  // Update the 'people' display on load and on updates
  peopleDataProvider.subscribePeople(undefined, (people) => {
    if (isPlatformError(people)) {
      logger.warn(`subscribePeople received PlatformError: ${getErrorMessage(people)}`);
      return;
    }
    const peopleData = document.getElementById('people-data');
    const peopleString = serialize(people, undefined, 2);
    peopleData.textContent = htmlEncode(peopleString.replace(/"/g, '`'));
    print(peopleString);
  });
  // Update the people update count on any people update
  let peopleUpdateCount = 0;
  peopleDataProvider.subscribePeople(
    undefined,
    () => {
      peopleUpdateCount += 1;
      const peopleUpdateCountDiv = document.getElementById('people-update-count');
      peopleUpdateCountDiv.textContent = htmlEncode(`People Updates: ${peopleUpdateCount}`);
    },
    { retrieveDataImmediately: false },
  );
  // Update the greetings count on greetings updates
  let billAnyGreetingsUpdateCount = 0;
  peopleDataProvider.subscribeGreeting(
    'BiLl',
    () => {
      billAnyGreetingsUpdateCount += 1;
      const billAnyGreetingsUpdateCountDiv = document.getElementById(
        'bill-any-greetings-update-count',
      );
      billAnyGreetingsUpdateCountDiv.textContent = htmlEncode(
        `Any Greetings Updates (via Bill): ${billAnyGreetingsUpdateCount}`,
      );
    },
    { retrieveDataImmediately: false, whichUpdates: '*' },
  );
  // Update the greetings count on greetings updates
  let billGreetingsUpdateCount = -1;
  peopleDataProvider.subscribeGreeting('bIlL', () => {
    billGreetingsUpdateCount += 1;
    const billGreetingsUpdateCountDiv = document.getElementById(
      'bill-greetings-update-count',
    );
    billGreetingsUpdateCountDiv.textContent = htmlEncode(
      `Bill Greetings Updates: ${billGreetingsUpdateCount}`,
    );
  });
  // Update the age count on age updates
  let billAnyAgeUpdateCount = 0;
  peopleDataProvider.subscribeAge(
    'BiLl',
    () => {
      billAnyAgeUpdateCount += 1;
      const billAnyAgeUpdateCountDiv = document.getElementById(
        'bill-any-age-update-count',
      );
      billAnyAgeUpdateCountDiv.textContent = htmlEncode(
        `Any Age Updates (via Bill): ${billAnyAgeUpdateCount}`,
      );
    },
    { retrieveDataImmediately: false, whichUpdates: '*' },
  );
  // Update the age count on age updates
  let billAgeUpdateCount = -1;
  peopleDataProvider.subscribeAge('bIlL', () => {
    billAgeUpdateCount += 1;
    const billAgeUpdateCountDiv = document.getElementById('bill-age-update-count');
    billAgeUpdateCountDiv.textContent = htmlEncode(`Bill Age Updates: ${billAgeUpdateCount}`);
  });
}

setupWebView();
```

--------------------------------

### Install Dependencies

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/legacy-comment-manager/README.md

Installs local and published dependencies for the extension. Requires prior installation of 'paranext-core'.

```bash
npm install
```

--------------------------------

### Preview Platform.Bible React Components

Source: https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/README.md

Starts a development server to preview the platform-bible-react components. The preview is located at `src/preview/app.component.tsx`.

```bash
npm start
```

--------------------------------

### Run Platform.Bible with Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/paratext-registration/README.md

Starts Platform.Bible with the built extension located in the 'dist' folder. The command-line argument for the extension path is included in the package.json 'start' script.

```bash
npm start
```

--------------------------------

### Start Platform.Bible with Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-get-resources/README.md

Starts Platform.Bible with the extension. The built extension is located in the 'dist' folder and is automatically referenced via a command-line argument in the package.json start script.

```bash
npm start
```

--------------------------------

### GitHub Actions Workflow Example

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/quick-verse/README.md

An example of a GitHub Actions workflow file for automating processes in the repository.

```yaml
name: CI

# Controls when the action will run.
# For example, running it only on push to the main branch:
on:
  push:
    branches: [ main ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can be run independently.
jobs:
  # The build job
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository into the workspace so your job can access it
      - uses: actions/checkout@v3
      # Runs a single command using the OS shell
      - name: Run a one-line script
        run: echo Hello, world!
      # Runs a set of commands using the OS shell
      - name: Run a multi-line script
        run: |
          echo Add other tools, just as 'make'
          echo Build the project
          npm install
          npm run build
```

--------------------------------

### Paranext Development Help and Resources

Source: https://github.com/paranext/paranext-core/wiki/Platform.Bible-and-Paratext-10-Studio

Provides links to the Platform.Bible Discord server, API documentation, troubleshooting guides, and React learning resources.

```Discord
https://discord.gg/tzw22PUEAY
```

```APIDOC
https://paranext.github.io/paranext-core/
```

```GitHub Wiki
https://github.com/paranext/paranext/wiki/Troubleshooting-Guide
```

```GitHub Wiki
https://github.com/paranext/paranext-extension-template/wiki
```

```Google Docs
https://docs.google.com/document/d/1sT85MJosKWHH4Kbljsl_Wmzy3bRdrlHav7faGA9GQmo/edit#heading=h.67pi94imi9qb
```

--------------------------------

### Run Platform.Bible with Extensions

Source: https://github.com/paranext/paranext-core/blob/main/extensions/README.md

Starts Platform.Bible with the included extensions. The built extensions are located in the 'dist' folder and are automatically watched for changes.

```bash
npm start
```

--------------------------------

### Running the Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-scripture-editor/README.md

Command to start Platform.Bible with the Paranext Core extension. It highlights the need to specify the extension path.

```bash
# Start Platform.Bible with the extension
npm start
```

--------------------------------

### Package.json Configuration

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-someone/README.md

This snippet shows the relevant parts of package.json for configuring the extension, including scripts for starting, watching, building, and packaging, as well as how it might reference external dependencies like paranext-core.

```json
{
  "name": "paranext-core",
  "version": "1.0.0",
  "scripts": {
    "start": "node run-platform.js --extensionPath=./dist",
    "watch": "npm run build -- --watch",
    "build": "tsc",
    "package": "npm run build && node scripts/package.js"
  },
  "devDependencies": {
    "@types/node": "^18.0.0",
    "typescript": "^5.0.0"
  }
}
```

--------------------------------

### Install Dependencies Command

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-scripture/README.md

Command to install local and published dependencies for the extension.

```bash
npm install

```

--------------------------------

### Start Platform.Bible Command

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-scripture/README.md

Command to run Platform.Bible with the extension included.

```bash
npm start

```

--------------------------------

### GitHub Actions Workflow Example

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-get-resources/README.md

An example of a GitHub Actions workflow file for automating processes in the repository.

```yaml
name: CI

# Controls when the action will run.
# For example, running it only on push to the main branch:
on:
  push:
    branches: [ main ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can be run independently.
jobs:
  # The build job
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository into the workspace so your job can access it
      - uses: actions/checkout@v3
      # Runs a single command using the OS shell
      - name: Run a one-line script
        run: echo Hello, world!
      # Runs a set of commands using the OS shell
      - name: Run a multi-line script
        run: |
          echo Add other tools, just as 'make'
          echo Build the project
          npm install
          npm run build
```

--------------------------------

### Package.json Configuration

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-rock3/README.md

This snippet shows the relevant parts of package.json for configuring the extension, including scripts for starting, watching, building, and packaging, as well as how it might reference external dependencies like paranext-core.

```json
{
  "name": "paranext-core",
  "version": "1.0.0",
  "scripts": {
    "start": "node run-platform.js --extensionPath=./dist",
    "watch": "npm run build -- --watch",
    "build": "tsc",
    "package": "npm run build && node scripts/package.js"
  },
  "devDependencies": {
    "@types/node": "^18.0.0",
    "typescript": "^5.0.0"
  }
}
```

--------------------------------

### Add Template Git Remote

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/quick-verse/README.md

Adds the paranext-extension-template repository as a remote named 'template'. This is a one-time setup command.

```bash
git remote add template https://github.com/paranext/paranext-extension-template
```

--------------------------------

### Add Template Git Remote

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-lexical-tools/README.md

Adds the paranext-extension-template repository as a remote named 'template'. This is a one-time setup command.

```bash
git remote add template https://github.com/paranext/paranext-extension-template
```

--------------------------------

### Add Template Git Remote

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-rock3/README.md

Adds the paranext-extension-template repository as a remote named 'template'. This is a one-time setup command.

```bash
git remote add template https://github.com/paranext/paranext-extension-template
```

--------------------------------

### Add Template Git Remote

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-someone/README.md

Adds the paranext-extension-template repository as a remote named 'template'. This is a one-time setup command.

```bash
git remote add template https://github.com/paranext/paranext-extension-template
```

--------------------------------

### Package.json Configuration

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-scripture-editor/README.md

This snippet shows the relevant parts of package.json for configuring the extension, including scripts for starting, watching, building, and packaging, as well as how it might reference external dependencies like paranext-core.

```json
{
  "name": "paranext-core",
  "version": "1.0.0",
  "scripts": {
    "start": "node run-platform.js --extensionPath=./dist",
    "watch": "npm run build -- --watch",
    "build": "tsc",
    "package": "npm run build && node scripts/package.js"
  },
  "devDependencies": {
    "@types/node": "^18.0.0",
    "typescript": "^5.0.0"
  }
}
```

--------------------------------

### DOMContentLoaded Setup

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-someone/src/hello-someone.web-view.html

Ensures that the `setupWebView` function is called after the DOM is fully loaded. It checks the `document.readyState` and either calls `setupWebView` immediately or adds an event listener for the `DOMContentLoaded` event.

```javascript
if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', setupWebView);
} else {
  setupWebView();
}
```

--------------------------------

### Add Template Git Remote

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-scripture-editor/README.md

Adds the paranext-extension-template repository as a remote named 'template'. This is a one-time setup command.

```bash
git remote add template https://github.com/paranext/paranext-extension-template
```

--------------------------------

### Run Storybook Locally

Source: https://github.com/paranext/paranext-core/blob/main/README.md

Starts the Storybook development server locally. This allows you to view and interact with your UI components in an isolated environment.

```bash
npm run storybook
```

--------------------------------

### Add Template Git Remote

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-get-resources/README.md

Adds the paranext-extension-template repository as a remote named 'template'. This is a one-time setup command.

```bash
git remote add template https://github.com/paranext/paranext-extension-template
```

--------------------------------

### Webpack Project Template for Platform.Bible Extensions

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-someone/README.md

This section describes the Webpack project template used for building Platform.Bible extensions. It outlines the basic structure and mentions that certain files and folders (like *.web-view.* and public/assets) are not included in this minimal template but can be found in other example extensions.

```html
<!-- Opening comment tag for Template Info Section. Ignore this for now. More info in [Hide Template Info](#hide-template-info).

## Template Info

This is a Webpack project template pre-configured to build a Platform.Bible extension. It contains the bare minimum of what an extension needs. Note that the `*.web-view.*` files and the `public/assets` folder mentioned in [Summary](#summary) are not present in this template. For inspiration on what these could look like, refer to any extension that is built using this template. An example would be the [Text Collection extension](https://github.com/paranext/paranext-extension-text-collection).

There is also a [template pre-configured to build an arbitrary number of Platform.Bible extensions in one repo](https://github.com/paranext/paranext-multi-extension-template).

### Customize extension details

Follow these instructions to customize the template to be your own Platform.Bible extension. This section is a more generalized version of the [`Your first extension` guide](https://github.com/paranext/paranext-extension-template/wiki/Your-First-Extension), which contains step-by-step instructions to build a "Hello World" extension.

#### Install and hook up to the template

Note: please skip this section and continue with [Replace placeholders](#replace-placeholders) if you are following these instructions as part of [creating an extension within `paranext-multi-extension-template`](https://github.com/paranext/paranext-multi-extension-template#to-create-a-new-extension-in-this-repo).

To make the process of customizing from the template as smooth as possible, we recommend you do the following before anything else:

- [Install and set up this repo](#to-install)
- [Update this extension from the template](#to-update-this-extension-from-the-template) to hook everything up for smooth updates in the future.
```

--------------------------------

### Install Dependencies for papi-dts

Source: https://github.com/paranext/paranext-core/blob/main/lib/papi-dts/README.md

Instructions for installing dependencies for the papi-dts package within the paranext-core project. This includes installing paranext-core dependencies and then running npm install within the papi-dts directory.

```bash
# Install paranext-core dependencies (refer to paranext-core documentation)
# Example: npm install in paranext-core directory

# Navigate to the papi-dts directory
cd paranext-core/lib/papi-dts

# Install published dependencies for papi-dts
npm install
```

--------------------------------

### UI Vocabulary and GenAI Drafts

Source: https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/Vocabulary.mdx

This section details a vocabulary for UI elements and provides drafts for AI-generated content, focusing on the nuances of action verbs like 'install vs. get', 'open vs. view', and 'remove vs. delete'. It also covers terms for UI components such as 'card', 'table', 'label', 'dropdown', 'combo box', 'search bar', 'header', 'footer', 'icon', 'dialog', 'separator', 'content', 'description', 'title', 'subtitle', 'sticky', and status indicators like 'installed', 'update available', 'unknown', 'showing', and 'results'.

```text
## Vocabulary that needs to be written

* resource
* action
* command


## genAI drafts for consideration

### install vs. get
Use get for actions that download and install a resource in one step. Use install only when the process is distinct from downloading.

"Get" is friendlier and less technical, making it more approachable for users.

### open vs. view
Use open for actions that launch a resource or project. Use view for read-only or preview actions.

"Open" implies full access and editing, while "view" suggests limited interaction.

### remove vs. delete
Use remove for actions that take a resource out of the app but do not erase it from disk. Use delete only when the resource is permanently erased.

"Remove" is safer and less alarming for users, reducing fear of accidental loss.

### update
Use update for actions that bring a resource to its latest version.

Avoid "refresh" or "upgrade" unless those terms have specific technical meaning.

### type
Use type to refer to the category of a resource (e.g., Scripture, Enhanced Resource).

### language
Use language to refer to the language of a resource. Avoid "locale" unless discussing localization or translation features.

### card
Use card for UI containers that group related information visually.

### table
Use table for UI elements that display resources in rows and columns.

### label
Use label for text elements that identify or describe UI components.

### dropdown
Use dropdown for menus that expand to show options.

### combo box
Use combo box for UI elements that combine a dropdown with text input.

### search bar
Use search bar for UI elements that allow users to find resources by text.

### header
Use header for the top section of a card or table.

### footer
Use footer for the bottom section of a card or table.

### icon
Use icon for small graphical elements representing actions or types.

### project
Use project to refer to a collection of resources or work in Paratext.

### provider
Use provider for components or services that supply data to the UI.

### viewer
Use viewer for components that display resources for reading or review.

### dialog
Use dialog for modal UI elements that prompt the user for input or confirmation.

### separator
Use separator for UI elements that divide groups of options or content.

### content
Use content for the main area displaying information or resources.

### description
Use description for text that explains or adds detail to UI elements.

### title
Use title for the main heading of a card, dialog, or page.

### subtitle
Use subtitle for secondary headings that provide context or detail.

### sticky
Use sticky for UI elements that remain visible while scrolling.

### installed
Use installed to indicate resources that are available for use in the app.

### update available
Use update available to indicate resources that can be updated to a newer version.

### unknown
Use unknown for types or statuses that are not recognized by the app.

### showing
Use showing to indicate the number of resources currently displayed.

### results
Use results to refer to the outcome of a search or filter operation.
```

--------------------------------

### Build Platform-Bible-Utils

Source: https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-utils/README.md

Builds the platform-bible-utils package. This command should be run after setting up the development environment.

```bash
npm run build
```

--------------------------------

### Creating Your First Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/README.md

Guidance on how to create a new Platform.Bible extension within the multi-extension repository. This section refers to a separate step for detailed instructions.

```markdown
#### Create your first extension in this repo

Follow the steps in [To create a new extension in this repo](#to-create-a-new-extension-in-this-repo) to create your first extension in this repo! You can follow the same steps to create new extensions as desired.
```

--------------------------------

### Build Platform-Bible-Utils from Paranext-Core

Source: https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-utils/README.md

Builds the platform-bible-utils package from the root paranext-core directory.

```bash
npm run build:platform-bible-utils
```

--------------------------------

### Packaging Paranext Core for Production

Source: https://github.com/paranext/paranext-core/blob/main/README.md

Packages the Paranext application for the local platform. This command is used to create a distributable build of the application.

```bash
npm run package
```

--------------------------------

### Building the Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-someone/README.md

Commands for building the extension, either continuously (watch) or as a one-time process.

```bash
# Watch for changes and rebuild
npm run watch

# Build the extension once
npm run build
```

--------------------------------

### GitHub Actions Workflow Example

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/legacy-comment-manager/README.md

Example of a GitHub Actions workflow for automating processes in the repository. This file is located in .github/workflows.

```yaml
name: CI

# Controls when the action will run.
# For example, running on push to the main branch
on:
  push:
    branches: [ main ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This job builds the extension
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository into the workspace so your job can access it
      - uses: actions/checkout@v3
      # Sets up Node.js environment
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      # Installs dependencies
      - run: npm install
      # Builds the extension
      - run: npm run build
      # Packages the extension
      - run: npm run package
      # Uploads the packaged extension as an artifact
      - uses: actions/upload-artifact@v3
        with:
          name: paranext-core-extension
          path: release/paranext-core.zip
```

--------------------------------

### Building the Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-rock3/README.md

Commands for building the extension, either continuously (watch) or as a one-time process.

```bash
# Watch for changes and rebuild
npm run watch

# Build the extension once
npm run build
```

--------------------------------

### Packaging the Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-someone/README.md

Command to package the built extension into a distributable zip file.

```bash
# Package the extension for distribution
npm run package
```

--------------------------------

### GitHub Actions Workflow

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-scripture/README.md

Example of a GitHub Actions workflow file for automation.

```yaml
name: Build and Release

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Use Node.js 18.x
      uses: actions/setup-node@v3
      with:
        node-version: '18.x'
    - run: npm install
    - run: npm run build
    - name: Upload artifact
      uses: actions/upload-artifact@v3
      with:
        name: dist
        path: dist/

```

--------------------------------

### React WebView Component

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-scripture/README.md

Example of a React component used for a web view within the extension.

```react
import React from 'react';

const MyWebView: React.FC = () => {
  return (
    <div>
      <h1>Hello from WebView</h1>
    </div>
  );
};

export default MyWebView;

```

--------------------------------

### Initialize Hello Someone Web View

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-someone/src/hello-someone.web-view.html

Sets up the web view by subscribing to age updates and attaching an event listener to a button that opens a new web view. It uses `peopleDataProvider.subscribeAge` for age updates and `papi.webViews.openWebView` to create new web views.

```javascript
let billAnyAgeUpdateCount = 0;
peopleDataProvider.subscribeAge( 'BiLl', () => {
  billAnyAgeUpdateCount += 1;
  const billAnyAgeUpdateCountDiv = document.getElementById('bill-any-age-update-count');
  billAnyAgeUpdateCountDiv.textContent = htmlEncode( `Any Age Updates (via Bill): ${billAnyAgeUpdateCount}`, );
}, {
  retrieveDataImmediately: false,
  whichUpdates: '*',
} );

// Update the age count on age updates
let billAgeUpdateCount = -1;
peopleDataProvider.subscribeAge('bIlL', () => {
  billAgeUpdateCount += 1;
  const billAgeUpdateCountDiv = document.getElementById('bill-age-update-count');
  billAgeUpdateCountDiv.textContent = htmlEncode(`Bill Age Updates: ${billAgeUpdateCount}`);
});

// Attach handler for new-web-view-button
const newWebViewButton = document.getElementById('new-web-view-button');
newWebViewButton.addEventListener('click', async () => {
  const webViewId = await papi.webViews.openWebView('helloSomeone.peopleViewer', {
    type: 'float',
    floatSize: {
      width: 450,
      height: 350,
    },
  });
  print(`New People webview id: ${webViewId}`);
});
```

--------------------------------

### Build Platform.Bible React from Core

Source: https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/README.md

Builds the platform-bible-react library from the root `paranext-core` directory.

```bash
npm run build:platform-bible-react
```

--------------------------------

### Add Template Git Remote

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/legacy-comment-manager/README.md

Adds the paranext-extension-template repository as a remote named 'template'. This is a one-time setup command.

```bash
git remote add template https://github.com/paranext/paranext-extension-template
```

--------------------------------

### Packaging the Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-rock3/README.md

Command to package the built extension into a distributable zip file.

```bash
# Package the extension for distribution
npm run package
```

--------------------------------

### Package Extension for Distribution

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-lexical-tools/README.md

Packages the built extension into a zip file, preparing it for distribution.

```bash
npm run package
```

--------------------------------

### Build Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-lexical-tools/README.md

Builds the extension once from the source files.

```bash
npm run build
```

--------------------------------

### Add Template Git Remote

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-scripture/README.md

Adds the paranext-extension-template repository as a remote named 'template'. This is a one-time setup command.

```bash
git remote add template https://github.com/paranext/paranext-extension-template
```

--------------------------------

### Add Template Git Remote

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/paratext-registration/README.md

Adds the paranext-extension-template repository as a remote named 'template'. This is a one-time setup command.

```bash
git remote add template https://github.com/paranext/paranext-extension-template
```

--------------------------------

### Package Extensions for Distribution

Source: https://github.com/paranext/paranext-core/blob/main/extensions/README.md

Packages the built extensions into a zip file for distribution. This command prepares the extensions for deployment.

```bash
npm run package
```

--------------------------------

### Development Vocabulary: 'badge'

Source: https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/Vocabulary.mdx

Defines 'badge' for small UI elements that indicate status or category, such as 'installed' or 'update available'.

```markdown
### badge

Use badge for small UI elements that highlight status or category (e.g., installed, update available).
```

--------------------------------

### Sample Extensions and AI Image Generator

Source: https://github.com/paranext/paranext-core/wiki/Platform.Bible-and-Paratext-10-Studio

Links to sample extensions and a specific AI image generator extension for Platform.Bible.

```GitHub
https://github.com/paranext/platform-bible-sample-extensions
```

```GitHub
https://github.com/tjcouch-sil/platform-bible-extension-verse-image-generator
```

--------------------------------

### Paranext Core Build and Release Information

Source: https://github.com/paranext/paranext-core/wiki/Platform.Bible-and-Paratext-10-Studio

Information on official builds, how to create them, and unofficial builds generated from the main branch.

```GitHub
https://github.com/paranext/paranext-core/releases
```

```GitHub
https://github.com/paranext/paranext-core?tab=readme-ov-file#publishing
```

```GitHub
https://github.com/paranext/paranext-core/actions/workflows/package-main.yml
```

--------------------------------

### Build Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/quick-verse/README.md

Builds the extension once from the source files.

```bash
npm run build
```

--------------------------------

### Packaging the Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-scripture-editor/README.md

Command to package the built extension into a distributable zip file.

```bash
# Package the extension for distribution
npm run package
```

--------------------------------

### Basic Build (No Lint)

Source: https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-utils/README.md

Performs a quick build without linting. Changes from this build should not be committed without a subsequent full build.

```bash
npm run build:basic
```

--------------------------------

### Manual Release and Version Bumping

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/hello-someone/README.md

Provides an alternative manual process for creating a pre-release and bumping versions. This involves packaging the project, manually creating a GitHub release with generated notes, and then using npm or git commands to update version numbers in package files and commit the changes.

```bash
npm run package
# Create a new pre-release in GitHub on tag `v<version>`
# Copy `.github/assets/release-body.md` into the release body
# Press the "Generate release notes" button in the release creation page to generate a changelog
# Attach contents of `release` folder to the release
```

```bash
npm run bump-versions <next_version>
```

```bash
git checkout -b bump-versions-<next_version>
npm version <next_version> --git-tag-version false
# Change version in each extension's `manifest.json`
git commit -a -m "Bumped versions to <next_version>"; git push -u origin HEAD
```

--------------------------------

### Building the Extension

Source: https://github.com/paranext/paranext-core/blob/main/extensions/src/platform-scripture-editor/README.md

Commands for building the extension, either continuously (watch) or as a one-time process.

```bash
# Watch for changes and rebuild
npm run watch

# Build the extension once
npm run build
```

--------------------------------

### Shared Type Declarations Example

Source: https://github.com/paranext/paranext-core/blob/main/src/declarations/README.md

Demonstrates how extensions and core can share and extend type declarations, such as command handlers, by declaring modules and extending interfaces.

```typescript
/* In core or extension */

declare module 'papi-shared-types' {
  interface CommandHandlers {
    // Define or extend command handlers here
    myCustomCommand: (arg: string) => Promise<number>;
  }
}

/* In core or extension */

// Usage example:
const handler: CommandHandlers['myCustomCommand'] = async (arg) => {
  console.log(`Received: ${arg}`);
  return arg.length;
};

```