datacommonsorg/docsite

Source files should be in its own directory

enjoythecode opened this issue · 0 comments

Issue

The markdown files that are used to build the documentation is at the top-level directory of this repository. This is an issue because non-documentation .md files also get built into production.

For example, the README of this repository is served at this link, which seems unintentional. LICENSE is also affected.

Also, since the source files are mixed with repository files in the top-level directory, it is hard to scan the contents and look for the file one is interested in!

Current Solution

Normally, pages that are not intended to be deployed are added to _config.yml under exclude. (see #140 )

However, this process is prone to human-errors (as evidenced by the README and LICENSE being exposed). They require manual upkeep to make sure the list is up-to-date, etc.

Proposed Change

I'd like to move all source files to its dedicated directory, perhaps called src or source. Then, jekyll configuration can be changed in one line to look at that directory for files to build. This Jekyll option is described in the official documentation.

This is a straightforward code change, and therefore it should be suitable for me as a first-time contributor.

Benefits

  1. Remove human error and effort from excluding/unpublishing irrelevant .md files to the production deployment.
  2. Better code organization, making it easier to understand the code structure and locate specific files.