Repository files navigation

This repo contains the source files for the "cortexjs.io" website.

git submodule initgit submodule update# Setup, make a dev build and start a servernpm start

# Pick-up changes in the dependent modulesnpm run update# Generate .md files for API and launch local servernpm start

npm run stage# Make a clean production build.# Output goes inside submodules/cortex-js.github.ionpm run restart# Validate that everything works well in the browser then...npm run deploy# submodules/cortex-js.github.io (a git submodule) gets pushed to cortex-js.github.io

The site is published using GitHub Pages. The main benefit of using GH Pages isthe workflow integration (pubshing to GH triggers an automatic update of thesite being served)

The content of the sites are authored primarily as Markdown files, processedwith Docusaurus to turn them into HTML/CSS.

The output is in thesubmodules/cortex-js.github.io directory. That directoryis a Gitsubmodule which is linked to thecortex-js.github.io repo. Thatrepo is the one published by GH Pages (for organization, only an entire repo canbe published, for projects, the contents can be contained in a/docsdirectory).

See alsosubmodules.

Thecortex-js.github.io repo must also include two additional files:

• .nojekyll which indicates to GitHub that it should not process the contentof this repo with Jekyll (since this is already the output from Jekyll)
• CNAME with a content ofcortexjs.io

These files are created when runningnpm run stage.

Use the Settings tab in thecortex-js.github.io repo to indicate the use of acustom domain.

In addition, the DNS entries forcortexjs.io must include the following:

• a CNAME record that points towww.cortex-js.io tocortex-js.io
• Four A records that point to
  • 185.199.108.153
  • 185.199.109.153
  • 185.199.110.153
  • 185.199.111.153

Thenpm run build command generates the documentation for the APIs from theTypeScript.d.ts file into thebuild/ directory.

The build process uses thetypedoc tool to parse the API header files andoutput ajson files in thebuild/ directory.

Note: To debug the converter, use the VSCode debugger. Select Debug > StartDebugging to start a debugging session right in VSCode.

Thebuild-guides script then converts thejson file into markdown in the./src/build directory, which can then be processed by eleventy withnpm run build ornpm start.

The CSS styling information is defined insrc/_sass/.

The API documentation should follow the Google Documentation Style Guide(https://developers.google.com/style/api-reference-comments) andhttps://developers.google.com/style

In addition, the TypeScript code should follow the Google Style Guide:https://google.github.io/styleguide/jsguide.html#naming

The project follows theGitHub standard for namingproject scripts.

To do a local build:

npm start

To do a build ready to be staged:

npm run stage

The "testing" of the generated site consist of checking links, and that thegenerated HTML is valid.