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

Steps

  1. Open the Terminal command line in macOS.
  2. Navigate to the docs folder in the command line.
  3. 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.
  4. Open http://localhost:4000 in the browser to see the site running locally.
  5. Modify a .html or .md file and refresh the page in the browser.

How the project is structured

The docs folder will contain the following main folders:

  • _layouts: This 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. It also supports the use of the liquid template language.
  • _includes: Contains HTML content that can be reused on different pages. For now, it contains various html elements that are used to populate the left-hand-nav (LHN).
  • assets: it will contain 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).
    • In order to organize the image files, we're going to have multiple sub-folders grouped by subject in the images folder.
  • hubs: it will contain two HTML files that will have the content of the Request Money and Send Money hub pages respectively.
  • articles: it will contain sub-folders for each stage and each of them will contain all the articles related to that stage or subsection.
  • _site: this will be the output folder that will contain the generated HTML files. This is the default name by Jekyll but can be changed. index.html: it will have the homepage content.

More details about the Jekyll project structure can be found here.

How to add a new Article

Add content

Copy the template file and rename it with the name of the article title, i.e. SmartScan.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 a new entry in the hub page

There are 3 main components in the hub page: 1. Stage title, 2. Row of Card buttons and 3. Card buttons.

<!-- 1. Stage title -->
<h2 id="request-money">
    Request Money
</h2>

<!-- 2. Row of Card buttons -->
<div class="cards-group">

    <!-- 3. Card buttons -->

    <a class="card" href="/articles/request-money/SmartScan">
        <div class="body">
            <div class="title">SmartScan</div>
        </div>
        <div class="right-icon">
            <i class="fa-solid fa-angle-right icon"></i>
        </div>
    </a>

    <a class="card" href="/articles/request-money/AnotherArticle">
        <div class="body">
            <div class="title">Another Article</div>
        </div>
        <div class="right-icon">
            <i class="fa-solid fa-angle-right icon"></i>
        </div>
    </a>

    <!-- More Card buttons here... -->

</div>

Add a Stage title (optional)

In order to add a new stage title in the hub page just copy and paste the following HTML block in the respective hub page and modify the values accordingly:

<h2 id="request-money">
    Request Money
</h2>

Where id is an arbitrary value that will help us to anchor this title to the LHN element.

Add a Row of Card buttons (optional)

If it's required, you can add a new row of Card buttons with the following HTML block:

<div class="cards-group">
    <!-- Add Cards components here -->
</div>

Add a Card button

A card button is the box that contains the article title and the caret right icon >. It navigates to the article when it's pressed.

In order to add a new Card button in the respective hub page (send-money/index.html or request-money/index.html) just copy and pase the following Card element:

<a class="card" href="/articles/request-money/SmartScan">
    <div class="body">
        <div class="title">SmartScan</div>
    </div>
    <div class="right-icon">
        <i class="fa-solid fa-angle-right icon"></i>
    </div>
</a>

Then replace the article title accordingly (in this case replace the value SmartScan with the new article title) and add a link to the relative path of the article (in this case replace ./request-money/SmartScan accordingly to the path of the new article file without the file extension).

Add a new entry in the LHN page

There are 2 main components in the LHN page associated with the hub you're adding an article to:

  1. Stage title anchor: which navigates the Stage title in the hub page and contains an unordered list of Article links.
  2. Article links: which navigate to the corresponding article page.
<!-- 1.Stage title anchor -->
<li><a href="#request-money">Request Money</a>
    <!-- 2. Article links -->
    <ul>
        <li><a href="./request-money/SmartScan">SmartScan</a></li>
        <li><a href="./request-money/AnotherArticle">Another Article</a></li>
        <!-- More Article links here... -->
    </ul>
</li>

<!-- More Stage title anchors here... -->

Add a new Stage title anchor (optional)

Just add copy and paste the following HTML block in the corresponding navigation tree file (either for Request Money or Send Money):

<li><a href="#request-money">Request Money</a>
    <!-- Article links will be here -->
</li>

Where "#request-money" is the ID of Stage title in the hub page (the same as in the example of the Add a Stage title (optional) section).

Add a new Article link

Add the next HTML block inside of the corresponding Stage title anchor:

<ul>
    <li><a href="./request-money/SmartScan">SmartScan</a></li>
</ul>

Where ./request-money/SmartScan will be the relative path of the file name (exactly the same as in the Add a Card button example above).

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/