Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Two small bugfixes for parser #1

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
+35 −34
Open

Two small bugfixes for parser #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bbb061c
fix paths issue on windows systems,
markkane Oct 11, 2022
1fe867d
add termsUrl support to options
markkane Oct 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 23 additions & 22 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ module.exports = {
```

Or, you can use it with extra options defined (with more examples in
the next sections):
the next sections):

```js
plugins: [
Expand Down Expand Up @@ -89,7 +89,7 @@ content here

### Use Patterns to Reference a Term

When writing docs inside `docs/*.md(x)` files, in order to refer to a term,
When writing docs inside `docs/*.md(x)` files, in order to refer to a term,
you may use the following syntax:


Expand All @@ -109,10 +109,10 @@ header of the term file:
> ---
> ```

After successfully running the script, the above occurrence will be replaced by
a reference (technically a React component) that will render `term_text` as a
link to the corresponding term page, which is in turn generated from the
`term_name` attribute; furthermore, *hovering* over `term_text` displays a term
After successfully running the script, the above occurrence will be replaced by
a reference (technically a React component) that will render `term_text` as a
link to the corresponding term page, which is in turn generated from the
`term_name` attribute; furthermore, *hovering* over `term_text` displays a term
summary, as extracted from the corresponding term page.

### Example Usage
Expand Down Expand Up @@ -143,9 +143,9 @@ with the word **Party** containing the described functionality.

### Testing the Changes Locally

After writing terms and patterns in your `.md` files, you can always validate
After writing terms and patterns in your `.md` files, you can always validate
these changes, by running a dry-run command, in order to see compile errors
and a sample output of all the changes that will be made from the actual
and a sample output of all the changes that will be made from the actual
script. You can do that by running:

```commandline
Expand All @@ -156,14 +156,14 @@ and you will see in the command line the expected output of the actual command.

### Generating the Terminology Documentation

When you are finished referencing terms and have written corresponding term
When you are finished referencing terms and have written corresponding term
pages, you can test this locally by running:

```commandline
yarn docusaurus parse
```

This will replace all `%%term_text|term_name%%` occurrences with the React
This will replace all `%%term_text|term_name%%` occurrences with the React
component supporting the required functionality.

### Generating the Glossary Page
Expand All @@ -180,15 +180,15 @@ mentioned above will be populated in the `glossary.md` page.

## When to Generate the Terminology Docs

As the terminology plugin actually edits all markdown files, your Git repository
will show changes in the `git diff` command. It is highly recommended to avoid
As the terminology plugin actually edits all markdown files, your Git repository
will show changes in the `git diff` command. It is highly recommended to avoid
committing the changes, as the plugin will no longer be able to detect
patterns that have been altered.
patterns that have been altered.

Your best case scenario will be to use the scripts in CI, just before building
Your best case scenario will be to use the scripts in CI, just before building
and deploying the documentation.

The following example of a Gitlab CI job shows how to perform these steps in
The following example of a Gitlab CI job shows how to perform these steps in
the CI environment:

```yaml
Expand All @@ -208,7 +208,7 @@ and then you can use the `build` directory to serve your documentation.

## Configuration Options

For using the plugin with the default options, you can provide just the plugin
For using the plugin with the default options, you can provide just the plugin
name in `docusaurus.config.js` file of your repository:

```js
Expand All @@ -217,12 +217,13 @@ name in `docusaurus.config.js` file of your repository:
]
```

You can also use some of the following options specified by wrapping the name
You can also use some of the following options specified by wrapping the name
and an options object in an array inside your configuration:

| Option | Description | Type | Default value |
|:--------------------:|:---------------------------------------------------------------------------------------------------------:|:------:|:------------------:|
| termsDir | the directory used to collect the term files | string | ./docs/terms |
| termsUrl | the path used link from the glossary to the term files | string | /docs/terms |
| glossaryFilepath | specify the directory and name of the glossary file | string | ./docs/glossary.md |
| patternSeparator | the special character used to separate `term_text` <br>and `term_name` in the replace pattern for parsing | string | \| |
| noParseFiles | array of files to be excluded from search/replace | array | [] |
Expand All @@ -233,7 +234,7 @@ and an options object in an array inside your configuration:

**IMPORTANT NOTE**: All file paths need to be relative to the
project's root directory. If you want to exclude a file, you should
write `./docs/excude-me.md`.
write `./docs/excude-me.md`.

Example:

Expand All @@ -253,7 +254,7 @@ plugins: [

## How to Contribute

To build and use the plugin locally in a project, apply changes etc., follow the
To build and use the plugin locally in a project, apply changes etc., follow the
instructions below.

Clone the repository [https://gitlab.grnet.gr/devs/docusaurus-terminology](https://gitlab.grnet.gr/devs/docusaurus-terminology)
Expand All @@ -268,7 +269,7 @@ yarn build
```

After running those commands, all packages will be initialized and
built, and you are ready for development.
built, and you are ready for development.

In the `website` directory there is a Docusaurus project, ready with
the plugin initialized, which can be used for testing purposes. There
Expand All @@ -285,7 +286,7 @@ yarn build

from the root directory of the repository. And then we are ready to
test everything in the local Docusaurus project, so we run the
following commands:
following commands:

```commandline
cd website
Expand All @@ -304,7 +305,7 @@ yarn build
And this will output our compiled website in a directory called
`build`. You can use a package named `serve` to create instantly a
nodejs webserver to serve these files (as used in the dockerfile). You
can run:
can run:

```commandline
yarn global add serve
Expand Down
2 changes: 1 addition & 1 deletion packages/parser/src/commands/glossary.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ async function glossary(options) {

// append terms to the glossary
for (const term of termsByType) {
const current_file_path = path.resolve(process.cwd(), options.glossaryFilepath);
const current_file_path = path.posix.resolve(process.cwd(), options.glossaryFilepath);
const relativePath = getRelativePath(current_file_path, term.filepath, options);
const glossaryTerm = getGlossaryTerm(term, relativePath);
glossaryContent = glossaryContent + glossaryTerm;
Expand Down
4 changes: 2 additions & 2 deletions packages/parser/src/commands/parser.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ async function parser(options) {
}

if (fs.lstatSync(options.docsDir).isFile() &&
path.extname(options.docsDir).includes(".md")) {
path.posix.extname(options.docsDir).includes(".md")) {
console.log(`! A single file to be parsed is given in option "docsDir":` +
` "${options.docsDir}"`);
allFiles = [options.docsDir];
Expand Down Expand Up @@ -97,7 +97,7 @@ async function parser(options) {
console.log("Exiting...");
process.exit(1);
}
const current_file_path = path.resolve(process.cwd(), filepath);
const current_file_path = path.posix.resolve(process.cwd(), filepath);
const relativePath = getRelativePath(current_file_path, termReference.filepath, options);
const component = `<Term popup="${termReference.hoverText}" ` +
`reference="${relativePath}" video="${termReference.video}">${text}</Term>`;
Expand Down
12 changes: 6 additions & 6 deletions packages/parser/src/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,15 @@ module.exports = function (context, opts) {
`using default directory "${DEFAULT_OPTIONS.termsDir}"\n`);
options = Object.assign({}, DEFAULT_OPTIONS, opts);
validateOptions(options);
options.termsUrl = path.join(context.baseUrl, options.termsDir, "/");
options.termsDir = path.resolve(options.termsDir) + "/";
options.docsDir = path.resolve(options.docsDir) + "/";
options.glossaryFilepath = path.resolve(options.glossaryFilepath);
options.termsUrl = path.posix.join(context.baseUrl, options.termsUrl, "/");
options.termsDir = path.posix.resolve(options.termsDir) + "/";
options.docsDir = path.posix.resolve(options.docsDir) + "/";
options.glossaryFilepath = path.posix.resolve(options.glossaryFilepath);
for (const [index,item] of options.noParseFiles.entries()) {
options.noParseFiles[index] = path.resolve(process.cwd(), item);
options.noParseFiles[index] = path.posix.resolve(process.cwd(), item);
}
for (const [index,item] of options.noGlossaryFiles.entries()) {
options.noGlossaryFiles[index] = path.resolve(process.cwd(), item);
options.noGlossaryFiles[index] = path.posix.resolve(process.cwd(), item);
}

return {
Expand Down
6 changes: 3 additions & 3 deletions packages/parser/src/lib.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ function splice(cont, idx, rem, str) {
}

function getHeaders(content) {
const index = content.indexOf("---", 1) + "---".length;
const index = content.indexOf("---") < 0 ? 0 : content.indexOf("---", 1) + "---".length;
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If a MD file has no header section this line could cause breaking changes to the file. If the file has no header the slice index should be 0.

// slice the headers of the file
return content.slice(0, index);
}
Expand Down Expand Up @@ -167,8 +167,8 @@ function getRelativePath(source, target, opts) {
const sourceDir = source.substr(0, source.lastIndexOf("/"));
const targetDir = target.substr(0, target.lastIndexOf("/"));
//const relative_url = path.relative(sourceDir, targetDir);
const relative_url = path.relative(opts.termsDir, targetDir);
const final_url = path.join(
const relative_url = path.posix.relative(opts.termsDir, targetDir);
const final_url = path.posix.join(
opts.termsUrl, relative_url, target.substr(target.lastIndexOf("/")));
// construct the final url by appending the target's filename
// if the relative url is empty, it means that the referenced
Expand Down