From b5dd5f42d5bc3300093598203ed2dd79f6868393 Mon Sep 17 00:00:00 2001 From: Thomas Mills Date: Wed, 7 Aug 2024 10:22:25 +0200 Subject: [PATCH] Feature/com 159 markdown config (#37) * Markdown docs * Readme updated for import-docs argument --- README.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e0acfb7..2966f50 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,25 @@ If a standard is labeled as a recommendation, it indicates that it is not widely ## How to contribute to this repo? -If you would like to include additional standards, please refer to the manual for instructions on implementing new standards. (TODO: Create a link to the implementation page of standards.) If you have any other matters to bring to our attention, you can contact us via Slack (#engineering-enablement) or Teams (DV - Engineering Enablement). +If you would like to include additional standards, please refer to the [manual for instructions on implementing new standards](https://developers.amsterdam/docs/general/project-documentation). If you have any other matters to bring to our attention, you can contact us via Slack (#engineering-enablement) or Teams (DV - Engineering Enablement). + +### Markdown rules + +This application uses Docusaurus, which creates documentation pages from `.md` (Markdown) and `.mdx` (Markdown + JSX) files. Docusaurus compiles each type into a React component. However, if during compilation it encounters invalid markup or markup it is unsure of, the compiler will stop and return an error. + +Therefore, it is a requirement that Markdown files are properly formatted otherwise this application can crash. When running the import script in this application, it will attempt to compile each Markdown file to ensure there are no errors present otherwise the file will be skipped. + +Documentation and various tools that can assist in validation markdown content: + +- Docusaurus markdown features +- GitHub has several in-depth pages regarding Markdown, formatting, syntax and advanced usage. +- Markdown basics and 10 minute tutorial +- MDX Playground + *Here you can toggle between `Input format` as `MDX` or `markdown` to test Markdown compilation* + +### Markdown metadata + +Docusaurus uses '[Front matter](https://docusaurus.io/docs/markdown-features#front-matter)' to override common template metadata, for example, page titles, OG meta data and more. A full list is available [here](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter). ## Docusaurus @@ -25,7 +43,7 @@ This website is built using [Docusaurus](https://docusaurus.io/), a modern stati ### Installation ```bash -npm run +npm i ``` ### Local Development @@ -44,6 +62,14 @@ npm run build This command generates static content into the `build` directory and can be served using any static contents hosting service. +### Import documentation + +```bash +npm run import-docs +``` + +This command downloads the latest markdown files from the [development-standards](https://github.com/Amsterdam/development-standards) repository. By default this will save documentation in the `docs` directory; to customize this directory you can give an argument with the desired path (after the `import-docs` command). + ### Deployment Using SSH: