From dcec58845022e09281b35c1a0d3b98b972d2a08d Mon Sep 17 00:00:00 2001 From: tlylt Date: Tue, 3 May 2022 15:28:52 +0800 Subject: [PATCH 1/2] Initial update --- docs/userGuide/gettingStarted.md | 98 +++++++++++++++++++++++- docs/userGuide/siteJsonFile.md | 5 +- packages/core/template/default/site.json | 4 +- packages/core/template/minimal/site.json | 46 +++++------ packages/core/test/unit/utils/data.js | 4 +- 5 files changed, 130 insertions(+), 27 deletions(-) diff --git a/docs/userGuide/gettingStarted.md b/docs/userGuide/gettingStarted.md index 970c9be69f..3eac1e1077 100644 --- a/docs/userGuide/gettingStarted.md +++ b/docs/userGuide/gettingStarted.md @@ -18,9 +18,35 @@ %%{{ icon_ticked }}%% [Node.js](https://nodejs.org) {{ node_version }} or higher installed +Simply install MarkBind's command-line interface package to build, serve and deploy a MarkBind site. +There are a few different to do this: + +https://blog.scottlogic.com/2018/04/05/npx-the-npm-package-runner.html +https://docs.npmjs.com/cli/v8/commands/npx +https://reactjs.org/docs/create-a-new-react-app.html#create-react-app +https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b + +* `npx` + * Calling npx markbind-cli when markbind-cli isn’t already in your $PATH will automatically install a package with that name from the npm registry for you, and invoke it. When it’s done, the installed package won’t be anywhere in your globals, so you won’t have to worry about pollution in the long-term. +* `npm - global installation` + * Install the package globally, and it will be available for all local projects. +* `package.json` + * Install the package locally, and manage its version using a package.json. + ++**1. Install MarkBind**++ Run the following command to install MarkBind. + + + + +If you are using MarkBind frequently, follow the steps in `package.json` to install it locally. + + + + +Install the package globally, and it will be available for all local projects. + ``` $ npm install -g markbind-cli ``` @@ -38,6 +64,41 @@ $ markbind v2.x.y Usage: ... ``` + + + +If you have not initialized an npm project, you can initialize one by running the following command. + +``` +$ npm init +``` +You will need to answer the prompts to create a package.json file. To get a default package.json file, run the following command. + +``` +$ npm init -y +``` +You can always adjust the content of your package.json later. + +Then, install the package locally as a dev-dependency. + +``` +$ npm install markbind-cli --save-dev +``` + +To make the commands available, add the following scripts to your package.json. + +``` +"scripts": { + "init": "markbind init", + "build": "markbind build", + "serve": "markbind serve", + "deploy": "markbind deploy -ci" +} +``` + + + + ++**2. Initialize a new Project (or Start with an existing Project)**++ @@ -45,9 +106,26 @@ Usage: ... Navigate into an empty directory and run the following command to initialize a skeletal MarkBind site in that directory. It will create several new files in the directory e.g., `index.md`, `site.json`. + + + +``` +$ npx markbind-cli init +``` + + + ``` $ markbind init ``` + + + +``` +$ npm run init +``` + + @@ -77,9 +155,27 @@ Run the following command in the same directory. It will generate a website from + + + +``` +$ npx markbind-cli serve +``` + + + + ``` $ markbind serve ``` + + + +``` +$ npm run serve +``` + + Do some changes to the `index.md` and save the file. The live preview in the Browser should update automatically to reflect your changes. @@ -89,6 +185,6 @@ To stop the web server, go to the console running the `serve` command and press 1. **Update the content of your site**. More info can be found in the [_User Guide: Authoring Contents_](authoringContents.html) section 1. **Deploy your site**. More info can be found in the [_User Guide: Deploying the Site_](deployingTheSite.html) section. - +1. **Update your MarkBind version when necessary**. {% from "njk/common.njk" import previous_next %} {{ previous_next('', 'authoringContents') }} diff --git a/docs/userGuide/siteJsonFile.md b/docs/userGuide/siteJsonFile.md index 5be59ec10c..c7bf3bf35a 100644 --- a/docs/userGuide/siteJsonFile.md +++ b/docs/userGuide/siteJsonFile.md @@ -43,7 +43,7 @@ Here is a typical `site.json` file: "layout": "subtopic" } ], - "pagesExclude": ["subsite/**/*.md"], + "pagesExclude": ["subsite/**/*.md", "node_modules/*"], "externalScripts": [ "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML" ], @@ -59,7 +59,8 @@ Here is a typical `site.json` file: "_site/*", "*.json", "*.md", - ".git/*" + ".git/*", + "node_modules/*" ], "plugins" : [ "filterTags" diff --git a/packages/core/template/default/site.json b/packages/core/template/default/site.json index 42cfed9ef7..d4a41e9898 100755 --- a/packages/core/template/default/site.json +++ b/packages/core/template/default/site.json @@ -8,8 +8,10 @@ "site.json", "*.md", "*.njk", - ".git/*" + ".git/*", + "node_modules/*" ], + "pagesExclude": ["node_modules/*"], "pages": [ { "src": "index.md", diff --git a/packages/core/template/minimal/site.json b/packages/core/template/minimal/site.json index d77b3adcf1..659551c65e 100644 --- a/packages/core/template/minimal/site.json +++ b/packages/core/template/minimal/site.json @@ -1,25 +1,27 @@ { - "baseUrl": "", - "titlePrefix": "", - "ignore": [ - "_markbind/layouts/*", - "_markbind/logs/*", - "_site/*", - "site.json", - "*.md", - "*.njk", - ".git/*" - ], - "pages": [ - { - "src": "index.md", - "title": "Hello World" - }, - { - "glob": ["**/index.md", "**/*.md"] - } - ], - "deploy": { - "message": "Site Update." + "baseUrl": "", + "titlePrefix": "", + "ignore": [ + "_markbind/layouts/*", + "_markbind/logs/*", + "_site/*", + "site.json", + "*.md", + "*.njk", + ".git/*", + "node_modules/*" + ], + "pagesExclude": ["node_modules/*"], + "pages": [ + { + "src": "index.md", + "title": "Hello World" + }, + { + "glob": ["**/index.md", "**/*.md"] } + ], + "deploy": { + "message": "Site Update." + } } diff --git a/packages/core/test/unit/utils/data.js b/packages/core/test/unit/utils/data.js index 52133ae8cf..b6d9ffde98 100644 --- a/packages/core/test/unit/utils/data.js +++ b/packages/core/test/unit/utils/data.js @@ -54,8 +54,10 @@ module.exports.SITE_JSON_DEFAULT = '{\n' + ' "site.json",\n' + ' "*.md",\n' + ' "*.njk",\n' - + ' ".git/*"\n' + + ' ".git/*",\n' + + ' "node_modules/*"\n' + ' ],\n' + + ' "pagesExclude": ["node_modules/*"],\n' + ' "pages": [\n' + ' {\n' + ' "src": "index.md",\n' From 200a10e23be135a7aea01e753e3e530f9ab7884d Mon Sep 17 00:00:00 2001 From: tlylt Date: Fri, 6 May 2022 08:14:32 +0800 Subject: [PATCH 2/2] Revert changes to gettingStarted --- docs/userGuide/gettingStarted.md | 102 +------------------------------ 1 file changed, 3 insertions(+), 99 deletions(-) diff --git a/docs/userGuide/gettingStarted.md b/docs/userGuide/gettingStarted.md index 3eac1e1077..365cd05304 100644 --- a/docs/userGuide/gettingStarted.md +++ b/docs/userGuide/gettingStarted.md @@ -18,35 +18,9 @@ %%{{ icon_ticked }}%% [Node.js](https://nodejs.org) {{ node_version }} or higher installed -Simply install MarkBind's command-line interface package to build, serve and deploy a MarkBind site. -There are a few different to do this: - -https://blog.scottlogic.com/2018/04/05/npx-the-npm-package-runner.html -https://docs.npmjs.com/cli/v8/commands/npx -https://reactjs.org/docs/create-a-new-react-app.html#create-react-app -https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b - -* `npx` - * Calling npx markbind-cli when markbind-cli isn’t already in your $PATH will automatically install a package with that name from the npm registry for you, and invoke it. When it’s done, the installed package won’t be anywhere in your globals, so you won’t have to worry about pollution in the long-term. -* `npm - global installation` - * Install the package globally, and it will be available for all local projects. -* `package.json` - * Install the package locally, and manage its version using a package.json. - ++**1. Install MarkBind**++ Run the following command to install MarkBind. - - - - -If you are using MarkBind frequently, follow the steps in `package.json` to install it locally. - - - - -Install the package globally, and it will be available for all local projects. - ``` $ npm install -g markbind-cli ``` @@ -64,68 +38,16 @@ $ markbind v2.x.y Usage: ... ``` - - - -If you have not initialized an npm project, you can initialize one by running the following command. - -``` -$ npm init -``` -You will need to answer the prompts to create a package.json file. To get a default package.json file, run the following command. - -``` -$ npm init -y -``` -You can always adjust the content of your package.json later. - -Then, install the package locally as a dev-dependency. - -``` -$ npm install markbind-cli --save-dev -``` - -To make the commands available, add the following scripts to your package.json. - -``` -"scripts": { - "init": "markbind init", - "build": "markbind build", - "serve": "markbind serve", - "deploy": "markbind deploy -ci" -} -``` - - - - ++**2. Initialize a new Project (or Start with an existing Project)**++ -  + Navigate into an empty directory and run the following command to initialize a skeletal MarkBind site in that directory. It will create several new files in the directory e.g., `index.md`, `site.json`. - - - -``` -$ npx markbind-cli init -``` - - - ``` $ markbind init ``` - - - -``` -$ npm run init -``` - - @@ -140,7 +62,7 @@ The `init` command populates the project with the [default project template](htt -  + Navigate to the project {{ tooltip_root_directory }}. @@ -155,27 +77,9 @@ Run the following command in the same directory. It will generate a website from - - - -``` -$ npx markbind-cli serve -``` - - - - ``` $ markbind serve ``` - - - -``` -$ npm run serve -``` - - Do some changes to the `index.md` and save the file. The live preview in the Browser should update automatically to reflect your changes. @@ -185,6 +89,6 @@ To stop the web server, go to the console running the `serve` command and press 1. **Update the content of your site**. More info can be found in the [_User Guide: Authoring Contents_](authoringContents.html) section 1. **Deploy your site**. More info can be found in the [_User Guide: Deploying the Site_](deployingTheSite.html) section. -1. **Update your MarkBind version when necessary**. + {% from "njk/common.njk" import previous_next %} {{ previous_next('', 'authoringContents') }}