/
Project documentation
Project documentation
Warning
This page is now hosted on https://odp.finos.org/docs/project-collaboration#project-website
There are different ways documentation can be written and published within FINOS.
- 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
- 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.
- 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; finos.github.io 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:
- 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.
- Hugo, an alternative to Docusaurus that generates static HTML using Go Templates and some predefined conventions
- Jekyll, a Ruby-based static site generator that is embedded in GitHub Pages; it is highly customisable using variables, custom layouts, HTML blocks
- 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.
, multiple selections available,
Related content
Docusaurus
Docusaurus
More like this
Project Collaboration on Github
Project Collaboration on Github
More like this
Docusaurus Build Action
Docusaurus Build Action
More like this
Development Infrastructure
Development Infrastructure
More like this
WhiteSource for GitHub.com
WhiteSource for GitHub.com
More like this
Open Developer Platform Project
Open Developer Platform Project
More like this
Need help? Email help@finos.org
we'll get back to you.
Content on this page is licensed under the CC BY 4.0 license.
Code on this page is licensed under the Apache 2.0 license.