# Welcome to the Expensify Help site

[Expensify Help](https://help.expensify.com/) is mainly composed of static HTML (`.html`) and Markdown (`.md`) files. We use [Jekyll](https://jekyllrb.com/) to generate a static site from those HTML and Markdown files.

### Table of Contents
* [Testing Locally](#testing-locally)
* [How the project is structured](#how-the-project-is-structured)
* [How to add a new Article](#how-to-add-a-new-article)
* [How the site is deployed](#how-the-site-is-deployed)

# Testing Locally

## Pre-requisites

- Clone and/or pull the [App repo](https://github.com/Expensify/App) to your local machine.
- Check the [requirements](https://jekyllrb.com/docs/installation/) to install Jekyll.
- Install Jekyll locally by running:

```bash
gem install bundler
cd docs
bundle install
```

- On newer versions of macOS/Xcode you may see a `bundle install` error similar to the following. You can workaround it by symlinking whichever version of `universal-darwin` you have. More info in [this SO](https://stackoverflow.com/a/65481787/18466468).

```bash
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX13.0.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/include/ruby-2.6.0/universal-darwin21/ruby/config.h', needed by arena.o'
```

```bash
cd /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX13.0.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/include/ruby-2.6.0/
ln -sf universal-darwin22 universal-darwin21
```

## Steps

1. Open the Terminal command line in macOS.
1. In the root folder of the repository, execute `npm run createDocsRoutes` to generate the file which contains the routes for the articles (without this, the site will appear empty).
1. Navigate to the `docs` folder in the command line.
1. Run `bundle exec jekyll serve --livereload`.
    - _Note: If you see an error like `Unable to load the EventMachine C Extension...`, try running `gem uninstall eventmachine && bundle install`. If that doesn't work just removing the `--livereload` flag should work._
1. Modify a `.html` or `.md` file and save your changes, and the browser should quickly auto-refresh.

## Troubleshooting

### Android Chrome emulator
To visit the site on the Android emulator, go to `10.0.2.2:4000`.

If you're getting an error page that says "Refused to connect", try running `adb reverse tcp:4000 tcp:4000` with your emulator open.


# How the project is structured

The [docs](https://github.com/Expensify/App/tree/main/docs) folder will contain the following main folders:

- *_layouts*: Contains HTML templates used by Jekyll to create pages in the static site. For now, it has only one file ([default.html](https://github.com/Expensify/App/blob/main/docs/_layouts/default.html)) which will render the common HTML elements and the assets on every page.
- *_includes*: Contains HTML content that can be reused on different pages. [Includes](https://jekyllrb.com/docs/includes/) can accept parameters and be nested, so they are quite powerful.
- *assets*: Contains the three sub-folders css, images, and js. The css folder can contain either .css or .sass files (where SASS files will be processed by Jekyll and it will generate a CSS file in an output folder also generated by Jekyll).
- *hubs*: Contains hubs that display various related articles, optionally grouped by sub-topic within the hub.
- *articles*: Contains sub-folders for each hub and each of them will contain all the articles related to that hub.
- *_data*: Contains [custom global data](https://jekyllrb.com/docs/datafiles/), available anywhere via liquid with the syntax `site.data.<filename>`. Notably, there is a file called [routes.yml](https://github.com/Expensify/App/blob/55f2c73d8e3bb0efd0e2a985c05f25e87d28f3cc/docs/_data/routes.yml) in there which defines the structure of the app and metadata for its pages. 
- *_site*: The output folder that contains the generated HTML files. This is the default name by Jekyll but can be changed. Files in here are generated and should not be manually edited.
- index.html: The main homepage content.

More details about the Jekyll project structure can be found [here](https://jekyllrb.com/docs/structure/). Note that all html files in this project support the use of the [liquid template language](https://shopify.github.io/liquid/).

# Terminology
- **Platform**: Expensify Classic and New Expensify are the two platforms. They are shown on the homepage.
  - **Hub**: A hub is a collection of related articles. It comprises of:
    - **Article**: The document that explains some feature.
    - **Subcategory**: A narrower collection of related articles.

To put it all together, this is the mental model that you should have.

- Expensify Classic (Platform)
  - Getting Started (Hub)
    - Invite Members (Article)
    - Security (Article)
    - Playbooks (Subcategory)
      - Small business guide (Article)
      - Big business guide (Article)

# How to create a new hub
Let's assume that we want to create a new hub called Billing and Subscriptions inside the platform New Expensify.

1. Open `docs/_data/_routes.yml`
2. Under New Expensify add
```
    - href: billing-and-subscriptions
      title: Billing & Subscriptions
      icon: /assets/images/subscription.svg
      description: Adjust billing...
```
3. Use an existing icon, or a new one by adding it to `docs/assets/images/`


Link the hub.
1. Go to `docs/new-expensify/hubs`
2. Create a new folder using the hub name `billing-and-subscriptions`
3. Inside the newly created folder, create `index.html` with the following content.
```
---
layout: default
title: Billing & Subscriptions
---

{% include hub.html %}
``` 

Add articles.
1. Go to `docs/articles/new-expensify`
2. Create a new folder with the hub name `billing-and-subscriptions`

You are now ready to start adding articles and subcategories inside the hub 🎉

# How to delete an existing hub
Let's assume we want to delete the hub `integrations` inside the platform Expensify Classic.
1. Open `docs/_data/_routes.yml`
2. Find the hub integrations and delete its href, icon, title and description.
3. Go to `docs/expensify-classic/hubs/`
4. Delete the folder with your hub name and all its contents. eg: `integrations/`

Delete all articles for the hub
1. Go to `docs/articles/expensify-classic/`
2. Delete the folder with your hub name and all its contents. eg: `integrations/`

# How to rename a hub
If you need help with how to do this on github. Follow this [slack thread 🧵](https://expensify.slack.com/archives/C02QSAC6BJ8/p1703012261896119?thread_ts=1702999732.847589&cid=C02QSAC6BJ8) in `#expensifyhelp`

Let's assume that we need to rename the hub `get-paid-back` to `payments` for the platform `New Expensify`
1. Go to `docs/new-expensify/hubs/`
2. Rename the folder `get-paid-back/` to `payments`
3. Go to `docs/articles/new-expensify/`
4. Rename the folder `get-paid-back/` to `payments`
5. Open docs/_data/_routes.yml 
6. Rename the href `get-paid-back` to `payments`
7. Change `title` to `Payments`

# How to change icon of a hub
1. Open `docs/_data/_routes.yml`
2. Under the platform and hub, replace the icon link `assets/images/send.svg`.
3. Use an existing icon, or a new one by adding it to `docs/assets/images/`

# How to create a new subcategory
Creating a new subcategory is as easy as creating a new folder. For example, if we want to create a new subcategory `HR Integrations` for the hub `Integrations` and platform `Expensify Classic`
1. Go to `docs/articles/expensify-classic/integrations`
2. Create a new folder `hr-integrations`

You can now begin adding articles inside the subcategory `hr-integrations/`.

# How to add a new Article

## Add content

Copy the [template](https://github.com/Expensify/App/blob/main/docs/TEMPLATE.md) file into the correct subdirectory of `docs/articles`. For example, if the article belongs in the `Bank Accounts` hub for the platform `Expensify Classic`, then copy the template into `docs/articles/expensify-classic/bank-accounts` directory.

Next, rename the copy with the name of the article title, i.e. `Connect-ANZ.md`. It is **important** that the article has `.md` extension (you can use dashes for spaces in the file name if it's needed). The dashes will be removed in the generated site page. 

The sections of the article will be filled and nested automatically in the LHN, just ensure to use the [heading markdown tags](https://www.markdownguide.org/cheat-sheet/) correctly.

## Add images
1. Drag and drop your image inside `docs/assets/images/`
2. Use the image in your article by adding the markdown `![Image description here]({{site.url}}/assets/images/your_image_name_here.png){:width="100%"}`

- Note to replace `your_image_name_here` with the name of image that you uploaded.
- Note to replace `Image description here`  with an apt description of the image.

If you're unfamiliar with github branches, PRs and confused how to add images and article in the same PR, head to this [slack thread 🧵](https://expensify.slack.com/archives/C02QSAC6BJ8/p1699632298177679?thread_ts=1699576284.768909&cid=C02QSAC6BJ8) in `#expensifyhelp`.

## Add videos
1. Upload your video to cloudflare.
2. Import the video in an article. You can do that by pasting the below snippet.
3. Replace `src` with the public URL for the video. **It should be cloudflarestream.com url**.
4. Make sure to remove `/manifest/video.x` from the url.


Without a custom thumbnail
```
{% include video.html src="https://customer-dtm7nf3ai7b93j1q.cloudflarestream.com/b81eabafe1391ab06901ddc19dcda161" %}
```

Optional: Add a custom thumbnail for the video. Replace `your-image.png` with a **16x9 aspect ratio image** from the `assets/images` directory.
```
{% include video.html thumbnail="assets/images/your-image.png" src="https://customer-dtm7nf3ai7b93j1q.cloudflarestream.com/b81eabafe1391ab06901ddc19dcda161" %}
```

## Add meta-description tags for SEO

At the top of template file we're going to find a few variables that will help us to define the meta-description of the article for SEO:

```
---
title: The title of the post, page, or document
description: A short description of the page's content
image: (Optional) URL to an image associated with the post, page, or document (e.g., /assets/page-pic.jpg)
---
```

Just update the content for each variable accordingly or remove it if the information is not available. More details [here](https://github.com/jekyll/jekyll-seo-tag/blob/master/docs/usage.md#usage).

# How to rename an article
Assume that we want to rename the article `The Free Plan` to `Freemium Features` for the hub `billing and plan types` in New Expensify platform.
1. Go to `docs/articles/new-expensify/billing-and-plan-types`
2. Rename `The-Free-Plan.md` to `Freemium-Features.md`. Use dashes for spaces in the file name.
3. Add an entry in redirects.csv for the old article pointing to the new article.

Note: It is important that the file has `.md` extension.

# How to hide an article temporarily
Video demo available [here 🧵](https://expensify.slack.com/archives/C02NK2DQWUX/p1717772272605829?thread_ts=1717523271.137469&cid=C02NK2DQWUX).
1. Open github's in built code editor by pressing `.` on your keyboard. ([instructions here](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor#opening-the-githubdev-editor))
2. Go to the article that you want to hide `docs/articles/...`.
3. Drag and drop the article inside the hidden folder `docs/Hidden/`.
4. Add a redirect for it in `docs/redirects.csv` to ensure that we don't have broken links. You can choose to point it to the home page or the article's hub.
5. Commit the changes and raise a PR.

# How the site is deployed
This site is hosted on Cloudflare pages. Whenever code is merged to main, the github action `deployExpensifyHelp` will run.

It will generate routes.yml using the script `createDocsRoutes`, build the Jekyll site housed in the `/docs` directory and deploy it straight to production. The help site is publicly discoverable at https://help.expensify.com/