Page Comparison

There are different ways documentation can be written and published within FINOS.

1. GitHub and Markdown, probably the simplest and most intuitive approach: every file written in MarkDown format and hosted in GitHub is automatically parsed and visualised by GitHub; the README.md file located at the root of a project directory is parsed in the GitHub project homepage, which is now a well established best practice to guide consumers to get started with a project. Read more on GitHub Readme doc page
2. GitHub Wiki is a service that is available for every GitHub repository; it can be enabled/disabled via the GitHub repository settings and provides a dedicated Git endpoint that can host Markdown files and generates its web version.
3. GitHub Pages, to customise the look 'n feel of the page and publish the HTML version of your project docs in a custom domain name (ie myproject.com), yet keeping Markdown as documentation language and GitHub as hosting system; GitHub Pages basically reads HTML and Markdown files from a specific repository folder or branch (configured via GitHub repo settings) onto an HTTP endpoint; for example, all contents in github.com/finos/finos.github.io are rendered out in finos.github.io . Additionally, GitHub Pages can be plugged with different interpreters, which allow to build more complex use cases is a basic example of GitHub Pages, which uses plain HTML (and Javascript) to build the website, but alternative interpreters can be plugged into GitHub Pages, such as:
   1. Docusaurus is the most complete and recommended tool to easily manage project documentation on GitHub; is allows to manage content in MarkDown files, configure navigation and sidebars, manage versioning and is highly customizable using React.
   2. Hugo, an alternative to Docusaurus that generates static HTML using Go Templates and some predefined conventions
   3. Jekyll, a Ruby-based static site generator , that is embedded in GitHub Pages; if the GitHub repository content adheres to Jekyll directory structure, GitHub will automatically parse it accordingly; a FINOS example is https://github.com/fdc3/api/tree/gh-pages ; Jekyll delivers advanced features, such as using it is highly customisable using variables, custom layouts, HTML blocks which can be generated by other build processes (ie redoc-cli) and much more.
   4. Hugo, an alternative to Jekyll written in GoLang; it is not embedded into GitHub Pages, but can be easily integrated with the help of Travis CI, which can run the hugo command on commit and push the resulting HTML code into a GitHub branch; the Travis CI pages deployer is a perfect fit for this need.
4. Atlassian Confluence can be used for any FINOS Program activity; each program has a dedicated Confluence Space (see the full list), where sub-pages can be created to host activity-specific documentation.