How to Publish

1. Install Dev Tools (First Time Only)

In Terminal, run these commands:

Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install VS Code

brew install --cask visual-studio-code

Install Git

brew install git

Install Node

brew install node@latest

---

2. Clone the Docs Project

Navigate to the directory you want the docs to live on your local machine.

In Terminal, run:

git clone https://github.com/TWMC-Development/docs-docs.git

Change directory to the docs-docs directory (the one we just pulled down / cloned from github)

cd docs-docs

---

3. Open the Project in VS Code

In Terminal, run:

code .

---

4. See Your Changes Locally

Install dependencies

npm install

Start VitePress server locally (so you can see your changes in real time):

In Terminal, run:

npm run docs:dev

Open the link shown in terminal (usually http://localhost:5173)

---

5. Pull Down the latest codebase

Gotcha

Always always always, when starting your new work, pull down any changes from the remote repo that others have pushed up that aren't on your local machine.

git pull origin main

---

6. Publish Your Changes

Decision Tree

New Subject (decision fork)

Gotcha

If you're submitting your work as a PR, you need to create your branch before you start building / writing documentation. Most things w docs probably don't call for new branches.

• If you're pushing straight to the main branch without a PR (pull request, think peer review), you don't need to create a new branch, your 'git push origin main' will go live to the main branch immediately.
• When using a PR workflow, your new branch will later merge into main after someone approves changes. That someone could be you but best practice for complicated things, someone else.

Info:
The typical naming convention for branches is:

<subject>/<detail>

Examples:
feature/ai-chat
docs/instagram-guide

Create your new branch

git checkout -b update-styling

This will both create and check out a new branch (if it isn't already created) for you to work in. When you are done, you submit these edits as a pull request. The branch will be merged with the main branch, bringing in your changes to the main codebase.

Prepping for your work:

Create a new folder + files inside of /docs
Build out the appropriate configuration in config.mjs under the key of 'sidebar'

`/* ... */`
{

text: "Publish", %% this should probably correspond to the directory you just created %%

collapsible: true,

items: [

{ text: "How to Publish", link: "/publish/how" }, %% this needs to match exactly w the directory and file you just created %%

],

},
`/* ... */`

Gotcha The object you create must end w a comma ' , ' or the config will not compile.

Old subject (decision fork)

find the file in question under /docs/parent directory/file 

Do your work (decision fork converge)

Punch out your ideas 

Check your work

Spin up your dev server

npm run docs:dev

If this doesn't work Check your package.json for your terminal commands 'npm run ___'

check your work/changes in the browser (vite.press typically runs on port 5173)

http://localhost:5173/

---

Decision Tree

For Immediate publishing (decision fork)

stage your changes:

git add .

commit them together and add a note / comment for future reference

git commit -m "Update docs"

push your local changes to the remote repository in github

git push origin main

On confirmation, your new changes will trigger the CI/CD pipeline to publish live (eta 2m)

For Peer Review (decision fork) => Publish aka Submit a pull request (pr)

Gotcha

When submitting a PR, you should have already created a new branch before making your changes / creating your new section.

stage your changes:

git add .

commit them together and add a note / comment for future reference

git commit -m "Update docs"

submit your changes to the branch you created

git push origin docs/my-new-branch-name-here

submit your branch to be reviewed and merged into main

gh pr create --base main --head my-new-branch-name-here --title "My PR Title" --body "Description of the changes"

On the Pull Request page in the GitHub web UI under the repo's url/pull/num someone can:

• View the pull request page
• Read your title and description
• Review the code changes (via the “Files changed” tab)
• Leave comments, request changes, or approve

Once approved, they or you will click “Merge pull request” and the CI/CD pipeline will trigger a new build for your changes to go live.

Note

for quick quick quick changes, don't bother w PR, just use 'git push origin main'