CONTRIBUTING.md

Contributing

This is a,

• TypeScript-based
• Next.js (i.e. React-based) static website bootstrapped with create-next-app. View the docs at nextjs.org/docs.

that uses,

• Bulma as the (only) frontend framework
• SCSS for styling
• unified for processing markup
• Prettier for formatting code
• ESLint for linting code

Project Structure

• components/: Reusable React components.
• guides/: Contains Doubtfire user guides.
  • [aud]/: Guides for the audience identified by aud.
    • [id].md: Markdown file that contains the content of the guide identified by id.
  • Meta.ts: Global metadata about guides.
• pages/: Next.js pages directory.
  • _app.tsx, _document.tsx: Custom Next.js App and Document.
  • _app.scss: Global styles.
  • Pages of the website.
• public/: Contains assets.
  • guides/: Contains assets relevant to guides.
    • [id]/: Contains assets relevant to the guide identified by id.

Prerequisites

1. Node.js >= 14.x.
2. Visual Studio Code with the following plugins,
   1. EditorConfig for VS Code
   2. ESLint
   3. Prettier - Code formatter
   4. Markdown All in One (recommended)
   5. Code Spell Checker (recommended)
   6. TODO Highlight (recommended)

Code Style

The project includes EditorConfig, Prettier, ESLint and VSCode Workspace configurations. VSCode, when configured with the prerequisite should automatically,

• Handle code formatting (of TypeScript, JavaScript and Markdown files) upon saving.
• Highlight any issues that the linter reveals.
• Highlight misspelled words.
• Type-check TypeScript sources.

If not using the tools recommended above,

• Use a EditorConfig-compliant text editor.
• Use the pretty:check and pretty:write NPM scripts to format the codebase according to the code style.
• Use the lint NPM script to run ESLint and fix any errors that it reveals before committing your changes.

Getting Started

1. Setup your development environment by installing the prerequisites.
2. Clone this repository, and cd into it.
3. Run npm install to install dependencies.

Development

1. Run npm run dev to launch the Next.js development server, which should serve the website locally. A localhost URL will be logged to the console.
2. Open the URL in a web browser.
3. Any changes to the TypeScript, React & SCSS sources of the website will cause the webpage to instantly refresh.
4. Any changes to the guides (i.e. Markdown sources) of will appear following a manual browser refresh. Please read the Authoring a Guide section for more information on authoring guides.

Example

The console session should look something like,

PS> npm run dev

> [email protected] dev doubtfire.io
> next dev

ready - started server on http://localhost:3000
event - compiled successfully
event - build page: /
wait  - compiling...
event - build page: /next/dist/pages/_error
event - compiled successfully

In this case, the URL is http://localhost:3000.

Publishing to GitHub Pages

The pages workflow is configured to build, export & push the website to GitHub Pages (i.e. the gh-pages branch).

To trigger this workflow,

• (Preferred) Either push commits to the pages branch.
• Or, manually trigger the workflow via GitHub Actions.

Authoring a Guide

1. Decide on the name, ID, and audience of the guide.
   The ID must be unique across all guides, not just those within its audience. The Audience type exported by guides/Meta.ts defines the possible values for the audience.

   Example

   For the purposes of this example, the following details will be used,

   • Name: A New Guide
   • ID: new-guide
   • Audience: student

2. Add the guide to the orderedGuides list of Meta.ts.
   This list defines the order in which the guide will be listed.

   Example

   orderedGuides: [
     ...
     'new-guide'
     ...
   ]

3. Create a Markdown file for the content of the guide.
   The file must be created within the guides/[audience] directory and must be named after the ID of the guide.

   Example

   In this case, the file will be guides/student/new-guide.md.

4. Add front matter to the guide.
   The RawGuideFrontMatter type exported by guides/Meta.ts defines the front matter expected to be defined on each guide.

   • The title, summary and authors fields are expected.
   • authors is a comma-delimited sequence of GitHub usernames (e.g. author1, author2 for two authors). These usernames can optionally be mapped to their names within the authorNames property of the default export of guides/Meta.ts.
   Example

   In this case, the front matter of the guide would be,

   ---
   title: A New Guide
   summary: Adding a new guide to Doubtfire.io
   authors: RavinduL
   ---
   

   The author name can be specified as,

   authorNames: {
     ...
     RavinduL: 'Ravindu Liyanapathirana',
   }

5. Author the content of the guide.
   The content will be in the markdown format, and must be typed below the front matter.

   • View the Markdown documentation at daringfireball.net/projects/markdown. Markdown content can include HTML where necessary.

   • The following markdown extensions can also be used,

     !> A tip
     

     ?> A warning
     

     x> An error
     

   • The contents of guides do not get automatically refresh upon saving, unlike TypeScript, React & SCSS sources. Manual reloading is therefore required to view changes.

   • Any images that have to be included in the guide must be placed in the public/guides/[id]/ directory (with [id] substituted with the guide ID).

   • CSS classes from the Bulma frontend framework can be used for formatting where necessary.

   Example

   In this case, the contents of the entire Markdown file (i.e. with the front matter) will be,

   ---
   title: A New Guide
   summary: Adding a new guide to Doubtfire.io
   authors: RavinduL
   ---
   
   **Lorem** _ipsum_ ~dolor~ sit amet consectetur adipisicing elit. Assumenda facere, sed deserunt pariatur quaerat
   possimus neque natus ratione blanditiis libero debitis animi ex totam at ducimus ipsum voluptates aut itaque.
   
   !> Here's a tip!
   
   

   Images must be uploaded to the directory public/guides/new-guide/.

• The new guide should appear on the website after a refresh.

  Example