diff --git a/docs/userGuide/cliCommands.md b/docs/userGuide/cliCommands.md index bc0d612bd5..ce182a81c5 100644 --- a/docs/userGuide/cliCommands.md +++ b/docs/userGuide/cliCommands.md @@ -76,10 +76,13 @@ MarkBind Command Line Interface (CLI) can be run in the following ways: * ``
Root directory. Default is the current directory.
{{ icon_example }} `./myWebsite` +* `-c`, `--convert`
+ Convert an existing GitHub wiki or `docs` folder into a MarkBind website. See [Converting an existing Github project]({{ baseUrl }}/userGuide/markBindInTheProjectWorkflow.html#converting-an-existing-github-project) for more information. {{ icon_examples }} * `markbind init` : Initializes the site in the current working directory. * `markbind init ./myWebsite` : Initializes the site in `./myWebsite` directory. +* `markbind init --convert` : Converts the Github wiki or `docs` folder in the current working directory into a MarkBind website.
diff --git a/docs/userGuide/markBindInTheProjectWorkflow.md b/docs/userGuide/markBindInTheProjectWorkflow.md index 1fb664808c..f3336881c8 100644 --- a/docs/userGuide/markBindInTheProjectWorkflow.md +++ b/docs/userGuide/markBindInTheProjectWorkflow.md @@ -36,5 +36,29 @@ You can keep the user docs in a separate directory (say `user-docs`) and set up Similarly, you can keep the dev docs in a separate directory (sey `dev-docs`) and set up Netlify to deploy the site when there is an update to the `master` branch; that way, developers can see the latest version of dev-docs via the Netlify site. +#### Converting existing project documentation/wiki + +MarkBind supports the automatic conversion of an existing GitHub wiki or `docs` folder containing Markdown files. + +A MarkBind conversion involves the following: +- Adding a Home page: If your project already has a `README.md` or `Home.md`, the content will be copied over to `index.md`. Otherwise, a default home page will be added. +- Adding an About Us page: If your project already has `about.md`, this will be used as the About page. Otherwise, a default About page will be added. +- Adding a top navigation bar. +- Adding a site navigation menu: If your project has a valid `_Sidebar.md` file, it will be used as the [site navigation menu](https://markbind.org/userGuide/tweakingThePageStructure.html#site-navigation-menus). Otherwise, the menu will be built from your project's directory structure and contain links to all addressable pages. +- Adding a custom footer: If your project has a valid `_Footer.md` file, it will be used as the website footer. Otherwise, a default footer will be added. + + + Conversion might not work if your project files have existing Nunjucks syntax. + + +To convert your existing project, follow these steps: +1. Navigate into the project directory. +1. Run `markbind init --convert` to convert the project. +1. You can now preview the website using `markbind serve` to view your newly converted MarkBind website. + + + You only need to run the conversion once. Once you have converted your project, you can proceed to edit it as a normal MarkBind project. + + {% from "njk/common.njk" import previous_next %} {{ previous_next('deployingTheSite', 'themes') }} diff --git a/index.js b/index.js index ff4d28d878..1bdce1b0e0 100755 --- a/index.js +++ b/index.js @@ -3,6 +3,7 @@ // Entry file for Markbind project const chokidar = require('chokidar'); +const fs = require('fs-extra-promise'); const liveServer = require('live-server'); const path = require('path'); const program = require('commander'); @@ -45,15 +46,33 @@ program program .command('init [root]') + .option('-c, --convert', 'convert a GitHub wiki or docs folder to a MarkBind website') .alias('i') .description('init a markbind website project') - .action((root) => { + .action((root, options) => { const rootFolder = path.resolve(root || process.cwd()); + const outputRoot = path.join(rootFolder, '_site'); printHeader(); + if (options.convert) { + if (fs.existsSync(path.resolve(rootFolder, 'site.json'))) { + logger.error('Cannot convert an existing MarkBind website!'); + return; + } + } Site.initSite(rootFolder) .then(() => { logger.info('Initialization success.'); }) + .then(() => { + if (options.convert) { + logger.info('Converting to MarkBind website.'); + new Site(rootFolder, outputRoot).convert() + .then(() => { + logger.info('Conversion success.'); + }) + .catch(handleError); + } + }) .catch(handleError); }); diff --git a/src/Site.js b/src/Site.js index 2684a00a5a..efeb6f5816 100644 --- a/src/Site.js +++ b/src/Site.js @@ -18,6 +18,7 @@ _.isBoolean = require('lodash/isBoolean'); _.isUndefined = require('lodash/isUndefined'); _.noop = require('lodash/noop'); _.omitBy = require('lodash/omitBy'); +_.startCase = require('lodash/startCase'); _.union = require('lodash/union'); _.uniq = require('lodash/uniq'); @@ -25,6 +26,7 @@ const url = {}; url.join = path.posix.join; const delay = require('./util/delay'); +const FsUtil = require('./util/fsUtil'); const logger = require('./util/logger'); const Page = require('./Page'); @@ -38,6 +40,7 @@ const TEMP_FOLDER_NAME = '.temp'; const TEMPLATE_ROOT_FOLDER_NAME = 'template'; const TEMPLATE_SITE_ASSET_FOLDER_NAME = 'markbind'; +const ABOUT_MARKDOWN_FILE = 'about.md'; const BUILT_IN_PLUGIN_FOLDER_NAME = 'plugins'; const BUILT_IN_DEFAULT_PLUGIN_FOLDER_NAME = 'plugins/default'; const FAVICON_DEFAULT_PATH = 'favicon.ico'; @@ -59,6 +62,8 @@ const LAYOUT_FOLDER_PATH = '_markbind/layouts'; const LAYOUT_SCRIPTS_PATH = 'scripts.js'; const LAYOUT_SITE_FOLDER_NAME = 'layouts'; const USER_VARIABLES_PATH = '_markbind/variables.md'; +const WIKI_SITE_NAV_PATH = '_Sidebar.md'; +const WIKI_FOOTER_PATH = '_Footer.md'; function getBootswatchThemePath(theme) { return path.join(__dirname, '..', 'node_modules', 'bootswatch', 'dist', theme, 'bootstrap.min.css'); @@ -114,6 +119,9 @@ const SITE_CONFIG_DEFAULT = { }, }; +const ABOUT_MARKDOWN_DEFAULT = '# About\n' + + 'Welcome to your **About Us** page.\n'; + const FOOTER_DEFAULT = '