diff --git a/website/docs/cli/index.mdx b/website/docs/cli/index.mdx deleted file mode 100644 index e69de29..0000000 diff --git a/website/docs/developer/_common/_get-project-sources.mdx b/website/docs/developer/_common/_get-project-sources.mdx index 2734711..1ae1f3f 100644 --- a/website/docs/developer/_common/_get-project-sources.mdx +++ b/website/docs/developer/_common/_get-project-sources.mdx @@ -18,14 +18,14 @@ To clone the stable branch (`master`), run the following commands in a terminal (on Windows use the Git Bash console): ```sh -mkdir ~/Work/npm-modules && cd ~/Work/npm-modules +mkdir ~/Work/npm-packages && cd ~/Work/npm-packages git clone https://github.com/xpack/xpm-js.git xpm-js.git ``` For **development** purposes, clone the `development` branch: ```sh -mkdir ~/Work/npm-modules && cd ~/Work/npm-modules +mkdir ~/Work/npm-packages && cd ~/Work/npm-packages git clone \ --branch development \ https://github.com/xpack/xpm-js.git xpm-js.git @@ -34,5 +34,5 @@ git clone \ Or, if the repo was already cloned: ```sh -git -C ~/Work/npm-modules/xpm-js.git pull +git -C ~/Work/npm-packages/xpm-js.git pull ``` diff --git a/website/docs/developer/index.mdx b/website/docs/developer/index.mdx index 28cc832..49e917c 100644 --- a/website/docs/developer/index.mdx +++ b/website/docs/developer/index.mdx @@ -16,6 +16,7 @@ date: 2024-10-25 13:10:00 +0300 --- + import customField from '@site/src/libs/customField'; import CodeBlock from '@theme/CodeBlock'; @@ -44,7 +45,7 @@ project and provides documentation on how to build and test the package. ## Satisfy dependencies ```sh -npm --prefix ~/Work/npm-modules/xpm-js.git install +npm --prefix ~/Work/npm-packages/xpm-js.git install ``` ## Add links for development @@ -53,7 +54,7 @@ To facilitate the use of this module in other packages, add a link from the central npm storage to this local development folder: ```sh -npm --prefix ~/Work/npm-modules/xpm-js.git link +npm --prefix ~/Work/npm-packages/xpm-js.git link ``` And in the projects referring it: @@ -68,7 +69,7 @@ The TypeScript compiler can automatically recompile modified files. For this, start it in `watch` mode. ```sh -npm --prefix ~/Work/npm-modules/xpm-js.git run compile-watch +npm --prefix ~/Work/npm-packages/xpm-js.git run compile-watch ``` @@ -137,8 +138,8 @@ As for any `npm` package, the standard way to run the project tests is via `npm run test`: ```sh -npm --prefix ~/Work/npm-modules/xpm-js.git install -npm --prefix ~/Work/npm-modules/xpm-js.git run test +npm --prefix ~/Work/npm-packages/xpm-js.git install +npm --prefix ~/Work/npm-packages/xpm-js.git run test ``` @@ -159,3 +160,5 @@ To trace TypeScript module resolution: ```json "compile": "tsc --traceResolution -p ./", ``` + + diff --git a/website/docs/getting-started/index.mdx b/website/docs/getting-started/index.mdx index f137a9a..fd9dd04 100644 --- a/website/docs/getting-started/index.mdx +++ b/website/docs/getting-started/index.mdx @@ -15,6 +15,10 @@ date: 2024-10-24 18:58:00 +0300 --- +import Link from '@docusaurus/Link'; + + + import Overview from './_overview.mdx' import Compatibility from './_compatibility.mdx' import Status from './_status.mdx' @@ -55,6 +59,8 @@ backwards incompatible changes are introduced to the public API. + + ## Maintainer & Developer info For information specific to maintainers and developers, please refer to @@ -70,6 +76,15 @@ The original content is released under the with all rights reserved to [Liviu Ionescu](https://github.com/ilg-ul). +MacStadium + +## Credits + +Special thanks to **MacStadium**, for providing the Apple Silicon +development infrastructure as part of their generous +[Free and Open Source Software](https://www.macstadium.com/company/opensource) +program. + ## Enjoyed using this project? Let us know! If you enjoyed using this project, please let us know! Here are some ways you can show your support: diff --git a/website/docs/install/_custom-install.mdx b/website/docs/install/_custom-install.mdx index 9193553..5225b5e 100644 --- a/website/docs/install/_custom-install.mdx +++ b/website/docs/install/_custom-install.mdx @@ -166,10 +166,10 @@ On macOS, if you followed the instructions in the prerequisites section, you should already have **npm** configured to use a location in the home folder. -```sh -% which xpm + { +`% which xpm /Users/ilg/.nvm/versions/node/${props.nodeVersion}/bin/xpm -``` +`} To test if **xpm** starts: diff --git a/website/docs/maintainer/index.mdx b/website/docs/maintainer/index.mdx index 3495290..9c8b819 100644 --- a/website/docs/maintainer/index.mdx +++ b/website/docs/maintainer/index.mdx @@ -17,6 +17,8 @@ date: 2024-10-24 23:59:00 +0300 --- + + import CodeBlock from '@theme/CodeBlock'; import customField from '@site/src/libs/customField'; @@ -109,8 +111,8 @@ Execute the npm script `clean` then `start` in the website sub-project, or run the following in a terminal: ```sh -npm --prefix ~/Work/npm-modules/xpm-js.git/website run clean -npm --prefix ~/Work/npm-modules/xpm-js.git/website run start +npm --prefix ~/Work/npm-packages/xpm-js.git/website run clean +npm --prefix ~/Work/npm-packages/xpm-js.git/website run start ``` Navigate to the **Maintainer Info** page, @@ -118,7 +120,7 @@ the **Fix possible open issues** section. ### Fix possible open issues -Check GitHub issues and pull requests: +Check GitHub Issues and Pull Requests: - https://github.com/xpack/xpm-js/issues - https://github.com/xpack/xpm-js/pulls @@ -196,7 +198,7 @@ to: - run the `generate-website-blog-post` npm script; this will add a file in the `website/blog` folder: ```sh -npm --prefix ~/Work/npm-modules/xpm-js.git/website run generate-website-blog-post +npm --prefix ~/Work/npm-packages/xpm-js.git/website run generate-website-blog-post ``` - edit the front matter properties @@ -232,7 +234,7 @@ npm install ----location=global xpm@next Validate the web site content in a local build via the npm `build` script: ```sh -npm --prefix ~/Work/npm-modules/xpm-js.git/website run build +npm --prefix ~/Work/npm-packages/xpm-js.git/website run build ``` ## Publish the website @@ -317,3 +319,5 @@ Credit to [Shields IO](https://shields.io) for the badges. - https://redfin.engineering/node-modules-at-war-why-commonjs-and-es-modules-cant-get-along-9617135eeca1 + + diff --git a/website/docs/project/about/index.mdx b/website/docs/project/about/index.mdx index 93e91b3..21f825a 100644 --- a/website/docs/project/about/index.mdx +++ b/website/docs/project/about/index.mdx @@ -10,6 +10,7 @@ date: 2024-10-24 23:58:00 +0300 --- + import Website from './_website.mdx' {/* ------------------------------------------------------------------------ */} @@ -18,11 +19,18 @@ import Website from './_website.mdx' ## The project + The **xPack Project Manager** project is part of the [xPack Reproducible Build Framework](https://xpack.github.io) and is hosted on GitHub as [`xpack/xpm-js`](https://github.com/xpack/xpm-js/). + +## The project history + +The **xPack Project Manager** history is presented +in a separate [History](/docs/project/history/) page. + ## The web site @@ -35,8 +43,9 @@ a senior computer engineer, with expertise in **C++/C embedded systems**, **RTOSes**, **build tools**, operating systems, compilers and Internet technologies. + He can be reached at [``](mailto:ilg@livius.net). Please note, this email address is provided as a courtesy. For all correspondence related to -the **xPack Project Manager** -project, kindly use the project [support](/docs/support/) page). +the **xPack Project Manager** project, +kindly use the project [support](/docs/support/) page). diff --git a/website/docs/support/index.mdx b/website/docs/support/index.mdx index 28ad665..782a58f 100644 --- a/website/docs/support/index.mdx +++ b/website/docs/support/index.mdx @@ -20,10 +20,22 @@ date: 2020-07-21 17:54:00 +0300 # How to get help for xpm + ## Quick links The quick answer is to use the -[GitHub Discussions](https://github.com/xpack/xpm-js/discussions) pages. +[GitHub Discussions](https://github.com/xpack/xpm-js/discussions) +pages. + + +## Web pages issues + +If you find any issues in the content of these pages (such as typos or +incorrect phrasing) or have suggestions for improving the documentation, +please share them through the +[GitHub Discussions](https://github.com/xpack/xpm-js/discussions) +pages. + ## Check documentation @@ -42,16 +54,19 @@ similar topics - check the [GitHub Issues](https://github.com/xpack/xpm-js/issues) tracker and the -[GitHub Pull requests](https://github.com/xpack/xpm-js/pulls) +[GitHub Pull Requests](https://github.com/xpack/xpm-js/pulls) for similar problems. ## Ask questions in GitHub Discussions If you still could not find a solution, if you have interesting use cases, if you have custom configurations, and generally if you have -any experience that you want to share with others, use the -[GitHub Discussions](https://github.com/xpack/xpm-js/discussions) pages, -and enter a **New discussion**; use the **Q&A** category for questions, **Ideas** for suggestions and **General** for anything else. +any experience that you want to share with others, +use [GitHub Discussions](https://github.com/xpack/xpm-js/discussions) +pages. +Enter a **New discussion**; use the **Q&A** category for questions, +**Ideas** for suggestions and **General** for everything else. + ## Register a new support ticket only if necessary @@ -70,6 +85,42 @@ for questions and support, **use the ::: + +## Stack Overflow + +For community help, you can also use +[Stack Overflow](https://stackoverflow.com/). +Tag your questions with `xpack`. + +:::tip + +Please be aware that there is another tag `elastic-x-pack` for a different +project, and some of their questions are tagged with `xpack` too. + +::: + +## The Discord channel + +For live discusssions among members, join the **xPack Community** on +[Discord](https://discord.gg/kbzWaJerFG). + +Currently, there are three channels available: + +- `#xpm` +- `#xpack-dev-tools` +- `#general` + +These channels are open for free discussions on their respective topics. + +However, for support, please use GitHub Discussions whenever possible. + +## X/Twitter + +New releases and other announcements are posted on +[X/Twitter](https://twitter.com/xpack_project). + +Follow the hashtag `#xpack_project` for the latest updates. + ## Use of private e-mail :::caution Please, please, please! diff --git a/website/docs/test/index.mdx b/website/docs/test/index.mdx index 2e6f24d..0c20118 100644 --- a/website/docs/test/index.mdx +++ b/website/docs/test/index.mdx @@ -69,7 +69,7 @@ Eight :::note -Some **content** with _Markdown_ `syntax`. Check [this `api`](#). +Some white **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: @@ -79,30 +79,32 @@ Some **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: -:::tip +:::info -Some **content** with _Markdown_ `syntax`. Check [this `api`](#). +Some blue **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: -:::info +:::tip -Some **content** with _Markdown_ `syntax`. Check [this `api`](#). +Some green **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: :::caution -Some **content** with _Markdown_ `syntax`. Check [this `api`](#). +Some orange **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: :::danger -Some **content** with _Markdown_ `syntax`. Check [this `api`](#). +Some red **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: +Jekyll `{% include note.html` must be replaced by `:::info`. + --- ## Expandable details @@ -182,7 +184,7 @@ const visit = require('unist-util-visit'); -To display hadings not showing in the TOC: +To display headings not showing in the TOC: My Heading diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 10a053c..da1346d 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -36,7 +36,12 @@ function getCustomFields() { logger.info(`package version: ${topPackageJson.version}`); - const customFields = {} + const enginesNodeVersion = topPackageJson.engines.node.replace(/[^0-9]*/, '') || ''; + const enginesNodeVersionMajor = enginesNodeVersion.replace(/[.].*/, ''); + const customFields = { + enginesNodeVersion, + enginesNodeVersionMajor + } return { releaseVersion, @@ -54,7 +59,8 @@ logger.info(customFields); // ---------------------------------------------------------------------------- const config: Config = { - title: 'xpm - The xPack Project Manager', + title: 'xpm - The xPack Project Manager' + + ((process.env.DOCUSAURUS_IS_PREVIEW === 'true') ? ' (preview)' : ''), tagline: 'A tool to automate builds, tests and manage C/C++ dependencies, inspired by npm', favicon: 'img/favicon.ico', @@ -62,7 +68,8 @@ const config: Config = { url: 'https://xpack.github.io/', // Set the // pathname under which your site is served // For GitHub pages deployment, it is often '//' - baseUrl: '/xpm-js/', + baseUrl: process.env.DOCUSAURUS_BASEURL ?? + '/xpm-js/', // GitHub pages deployment config. // If you aren't using GitHub pages, you don't need these. diff --git a/website/package.json b/website/package.json index 444fc58..311b48f 100644 --- a/website/package.json +++ b/website/package.json @@ -16,7 +16,7 @@ "typecheck": "tsc", "npm-outdated": "npm outdated", "npm-install": "npm install", - "npm-link-deps": "npm link @xpack/docusaurus-template-liquid @xpack/node-modules-helper", + "npm-link-helper": "npm link @xpack/docusaurus-template-liquid @xpack/npm-packages-helper", "generate-website-commons": "bash node_modules/@xpack/docusaurus-template-liquid/maintenance-scripts/generate-commons.sh", "generate-website-blog-post": "bash node_modules/@xpack/docusaurus-template-liquid/maintenance-scripts/generate-blog-post.sh" }, diff --git a/website/sidebars.ts b/website/sidebars.ts index df54b4f..5419ed4 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -17,6 +17,7 @@ import {userSidebarCategory} from "./sidebar-user"; */ const sidebars: SidebarsConfig = { + docsSidebar: [ { type: 'doc', @@ -48,6 +49,10 @@ const sidebars: SidebarsConfig = { type: 'category', label: 'Project', collapsed: false, + link: { + type: "doc", + id: "project/about/index", + }, items: [ { type: 'doc',