Skip to content

Latest commit

 

History

History
204 lines (151 loc) · 11.1 KB

README.md

File metadata and controls

204 lines (151 loc) · 11.1 KB
Raw

Welcome to the Expensify Help site

Expensify Help is mainly composed of static HTML (.html) and Markdown (.md) files. We use Jekyll to generate a static site from those HTML and Markdown files.

Table of Contents

Testing Locally

Pre-requisites

  • Clone and/or pull the App repo to your local machine.
  • Check the requirements to install Jekyll.
  • Install Jekyll locally by running:
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.
/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'
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.
  2. 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).
  3. Navigate to the docs folder in the command line.
  4. 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.
  5. 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 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) 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 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, available anywhere via liquid with the syntax site.data.<filename>. Notably, there is a file called 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. Note that all html files in this project support the use of the liquid template language.

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...
  1. 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 🧵 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 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/expensiyfy-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 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 🧵 in #expensifyhelp.

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.

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 🧵.

  1. Open github's in built code editor by pressing . on your keyboard. (instructions here)
  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/