From c20813a7316d0547d4b421b94b05af18f3a75709 Mon Sep 17 00:00:00 2001 From: InAnYan Date: Wed, 14 Aug 2024 14:54:45 +0300 Subject: [PATCH] Move advanced contribution hints --- README.md | 45 ------------------ .../how-to-improve-the-help-page.md | 47 ++++++++++++++++++- 2 files changed, 46 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 20b80f170..511bd627d 100644 --- a/README.md +++ b/README.md @@ -7,48 +7,3 @@ This repository serves the content of , which is the d - :point_right: To **contribute text** follow [our guide rendered by GitBook](https://docs.jabref.org/contributing/how-to-improve-the-help-page). In case you plan larger contributions, please contact us to gain access to the WYSIWG editor on GitBook itself. - :point_right: Feel free to **contribute ideas** using the [issue tracker](https://github.com/JabRef/user-documentation/issues). - -## Advanced Contribution Hints - -### How to regenerate `SUMMARY.md` from scratch - -Use . - -### How to find broken links - -1. Install [markdown-link-check](https://github.com/tcort/markdown-link-check): `npm install -g markdown-link check` -2. `find . -name \*.md -exec markdown-link-check -qq {} \; > bad-links.txt` - -### How to find Markdown errors - -You can use the [markdown-lint docker image](https://github.com/marketplace/actions/markdown-linting-action): - -```shell -docker run --rm \ - -v "$(pwd):/tmp/check" \ - -e INPUT_CONFIG=/tmp/check/.markdownlint.yml \ - avtodev/markdown-lint:v1 \ - /tmp/check/en -``` - -Alternatively, you can run the GitHub Lint workflow: - -```shell -act --rm --platform ubuntu-latest=fwilhe2/act-runner:latest -W .github/workflows/lint.yaml -``` - -### How to rename files - -The gitbook integration changes some of the file names and appends "(1) (2) (1)" or something like this. -If one fixes that in the GitHub repository, then the next sync rewrites the names again. -The only solution we've found so far is manually replacing the images using the GitBook UI: -Left to the image you have a hamburger with a "replace" option. - -In case GitBook was fixed, with some command line magic, this could be solved: - -1. Create a script renaming all images: `fd -e png -x bash -c "echo '{}' | sed 's/\([^(]*\)\(.*\).png/mv \"\\1\\2.png\" \"\\1.png\"/' | sed 's/ \.png/.png/'" | sort > fix-filenames.sh`. -2. Execute in `en/.gitbook`. Otherwise, `fd` does not find any file. -3. Repeat for `gif` instead of `png`. -4. Create a script doing the renaming in all `.md` files: `fd -e md -x bash -c "echo sed -i '\"s/assets\/\([^%]*\)\(.*\).png/assets\/\\1.png/\"' {}" > fix-mds.sh`. -5. Execute in the root repository. -6. Repeat for `gif` instead of `png`. diff --git a/en/contributing/how-to-improve-the-help-page.md b/en/contributing/how-to-improve-the-help-page.md index 1971e55c9..8f51cbbef 100644 --- a/en/contributing/how-to-improve-the-help-page.md +++ b/en/contributing/how-to-improve-the-help-page.md @@ -48,10 +48,55 @@ Just press the "Create Pull Request" button, and confirm the creation of the req That's it! The JabRef team will review your changes and publish them on [docs.jabref.org](https://docs.jabref.org). -## Advanced editing +## Advanced Contribution Hints + +### Advanced editing To edit more than one file at a time, add screenshots, and for other more advanced changes, we recommend that you checkout this repository locally and create a Pull Request of your changes using the standard git and GitHub workflow. ### Tables The best way to enter tables is to use this [Table Generator](http://www.tablesgenerator.com/markdown\_tables) for Markdown. It has the nice feature to generate markdown tables from different sources, e.g. you can directly copy the table from a spreadsheet or upload a csv file. Just copy and paste the generated markdown into the documentation. + +### How to regenerate `SUMMARY.md` from scratch + +Use . + +### How to find broken links + +1. Install [markdown-link-check](https://github.com/tcort/markdown-link-check): `npm install -g markdown-link check` +2. `find . -name \*.md -exec markdown-link-check -qq {} \; > bad-links.txt` + +### How to find Markdown errors + +You can use the [markdown-lint docker image](https://github.com/marketplace/actions/markdown-linting-action): + +```shell +docker run --rm \ + -v "$(pwd):/tmp/check" \ + -e INPUT_CONFIG=/tmp/check/.markdownlint.yml \ + avtodev/markdown-lint:v1 \ + /tmp/check/en +``` + +Alternatively, you can run the GitHub Lint workflow: + +```shell +act --rm --platform ubuntu-latest=fwilhe2/act-runner:latest -W .github/workflows/lint.yaml +``` + +### How to rename files + +The gitbook integration changes some of the file names and appends "(1) (2) (1)" or something like this. +If one fixes that in the GitHub repository, then the next sync rewrites the names again. +The only solution we've found so far is manually replacing the images using the GitBook UI: +Left to the image you have a hamburger with a "replace" option. + +In case GitBook was fixed, with some command line magic, this could be solved: + +1. Create a script renaming all images: `fd -e png -x bash -c "echo '{}' | sed 's/\([^(]*\)\(.*\).png/mv \"\\1\\2.png\" \"\\1.png\"/' | sed 's/ \.png/.png/'" | sort > fix-filenames.sh`. +2. Execute in `en/.gitbook`. Otherwise, `fd` does not find any file. +3. Repeat for `gif` instead of `png`. +4. Create a script doing the renaming in all `.md` files: `fd -e md -x bash -c "echo sed -i '\"s/assets\/\([^%]*\)\(.*\).png/assets\/\\1.png/\"' {}" > fix-mds.sh`. +5. Execute in the root repository. +6. Repeat for `gif` instead of `png`.