Skip to content

Latest commit

 

History

History
 
 

docs

README.md

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.

How to add a new Article

Add content

Copy the template file into the correct subdirectory of /articles. For example, if the article belongs in the Send money hub and Workspaces section, then copy the template into articles/send-money/workspaces directory. Next, rename the copy with the name of the article title, i.e. The-Free-Plan.md (you can use dashes for spaces in the file name if it's needed) and put the new file inside of the respective hub folder or sub-folder. The title will be rendered automatically according to the filename (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 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.

Add the new page to routes.yml

Next, run the command npm run createDocsRoutes to add the article to _data/routes.yml. Note that hubs contain one or more articles, which may or may not be grouped into sections with other related articles. All articles grouped under a section will be under the same subfolder in the hub folder.

If you have added a new hub, make sure to update the _routes.yml with the folder name, title, icon and description of the hub.

How the site is deployed

This site is hosted on GitHub Pages. GitHub Pages has a built-in Jekyll integration, and we have it configured such that whenever code is merged to main, GitHub will automatically 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/