This repository has been archived on 2023-08-16. You can view files and clone it, but cannot push or open issues or pull requests.
footnotes/README.md

175 lines
7.7 KiB
Markdown
Raw Permalink Normal View History

2021-04-20 02:21:37 +00:00
# footnotes
<!-- markdownlint-disable MD013 -->
2021-04-18 20:29:58 +00:00
![stable tag](https://img.shields.io/wordpress/plugin/v/footnotes?style=flat-square) ![WP rating](https://img.shields.io/wordpress/plugin/stars/footnotes?style=flat-square) ![Reqd PHP](https://img.shields.io/wordpress/plugin/required-php/footnotes?style=flat-square) ![Reqd WP](https://img.shields.io/wordpress/plugin/wp-version/footnotes?style=flat-square) ![WordPress Plugin: Tested WP Version](https://img.shields.io/wordpress/plugin/tested/footnotes?style=flat-square)
![GitHub contributors](https://img.shields.io/github/contributors/markcheret/footnotes?style=flat-square) ![GitHub commits since tagged version](https://img.shields.io/github/commits-since/markcheret/footnotes/2.7.0?style=flat-square) ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/markcheret/footnotes?style=flat-square) ![issues](https://img.shields.io/github/issues/markcheret/footnotes?style=flat-square) ![PRs](https://img.shields.io/github/issues-pr/markcheret/footnotes?style=flat-square)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) ![Snyk Vulnerabilities for GitHub Repo](https://img.shields.io/snyk/vulnerabilities/github/markcheret/footnotes?style=flat-square) [![OSSAR](https://github.com/markcheret/footnotes/actions/workflows/ossar-analysis.yml/badge.svg)](https://github.com/markcheret/footnotes/actions/workflows/ossar-analysis.yml) [![Code Linting](https://github.com/markcheret/footnotes/actions/workflows/php.yml/badge.svg)](https://github.com/markcheret/footnotes/actions/workflows/lint-code.yml)
2021-04-18 19:58:11 +00:00
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
<!-- markdownlint-enable MD013 -->
![footnotes](https://raw.githubusercontent.com/markcheret/footnotes/main/.github/img/footnotes.png)
**footnotes** aims to be the all-in-one solution for displaying an
automatically-generated list of references on your Page or Post. The Plugin
ships with a set of defaults while also empowering you to control how your
2021-04-14 22:21:01 +00:00
footnotes will be displayed.
2021-02-20 19:18:41 +00:00
**footnotes** gives you the ability to display well-formatted footnotes on your
2021-04-14 22:21:01 +00:00
WordPress Pages and Posts — those footnotes we know from offline publishing.
2021-02-20 19:18:41 +00:00
2021-04-18 19:58:11 +00:00
Featured on [wpmudev][wpmudev] — cheers for the review, folks!
2021-04-14 22:21:01 +00:00
## Table of Contents
2021-02-20 19:18:41 +00:00
2021-04-14 22:21:01 +00:00
* [Features](#features)
* [Getting Started](#getting-started)
* [Deploying](#deploying)
* [Testing](#testing)
* [Code Formatting](#code-formatting)
* [Documentation](#documentation)
* [Acknowledgments](#acknowledgements)
* [License](#license)
* [Contact Information](#contact-information)
2021-04-14 22:21:01 +00:00
## Features
2021-04-14 22:21:01 +00:00
This Plugin provides:
* fully customizable footnote start and end shortcodes;
* stylable tooltips supporting hyperlinks and dedicated text;
* a responsive 'reference container', with customisable positioning;
* a wide choice of different numbering styles;
* a freely-configurable and optional backlink symbol;
* footnote appearance customisation via dashboard settings and custom CSS style
2021-04-14 22:21:01 +00:00
rules; and
* editor buttons for easily adding shortcode tags.
2021-04-14 22:21:01 +00:00
## Getting Started
Add release helper script (#64) This commit adds a release helper script, amongst other workflow improvements. See `README.md` for instructions, and `_tools/release.sh` for the script itself. This script: 1. sanity-checks the various version tags; 2. triggers a Plugin build; 3. flags the new version as pre-release; 4. tags the version in Git; 5. creates a local working copy of the SVN repo; 6. copies the new release to the local `trunk/` (whilst keeping the ‘Stable Tag’ field in `readme.txt` pointing to the previous stable version); 7. copies the commit message from the changelog in `readme.txt`; and 8. (if a flag is set) commits the changes to the remote `trunk/`. Pushing out a new release must still be done manually, once `trunk/` is tested and working. To do so, check out a local copy of `trunk/` and: 1. update the ‘Stable Tag’ field in `trunk/readme.txt` to the new version; 2. update the ‘Version’ field in the comment header of `trunk/footnotes.php` to the new version; 3. remove the ‘p’ from the end of the ‘version’ tag in the `getInfo()` function at the bottom of `js/wsiwyg-editor.js`; 4. copy a new tag for the release from `trunk/` (`svn cp trunk tags/<version number>`); and 5. commit your changes (`svn ci -m "Release version <version number>"`). The WP Plugin Directory will automatically parse the ‘Stable Tag’ field in `trunk/readme.txt`, and inform users that a new version is available. At various stages user input is required to validate information. This is not ready for automation with GitHub Actions, but is a useful step on the way — see [this piece](https://blog.danslimmon.com/2019/07/15/do-nothing-scripting-the-key-to-gradual-automation/) for more info. Unless a `-c` flag is passed (e.g., by running `composer run release:commit`) no changes will take place on the remote SVN repo. If you want to test this out on a branch other than `main`, uncomment lines 31 & 52 of the script. Version checking enforces the versioning rules stated [here](https://github.com/markcheret/footnotes/wiki/Versioning). **NB: I have not tested the `-c` mode yet, as I wanted people will more familiarity with the SVN to have a look at it before I risked making any changes and blowing everything up.** Co-authored-by: pewgeuges <73141620+pewgeuges@users.noreply.github.com>
2021-03-17 17:46:21 +00:00
2021-04-14 22:21:01 +00:00
1. Read the [contributing guidelines][contributing];
1. clone this repository (`git clone git@github.com:markcheret/footnotes.git`):
* we recommend that you use [VVV][vvv] for your local testing environment.
2021-04-15 14:03:09 +00:00
1. install [Composer][composer] and [NPM][npm]; and
2021-04-14 22:21:01 +00:00
1. install all dependencies (`composer install`):
* you will have to install `php-mbstring` manually if you do not already
2021-04-14 22:21:01 +00:00
have it.
2021-04-14 22:21:01 +00:00
## Deploying
Add release helper script (#64) This commit adds a release helper script, amongst other workflow improvements. See `README.md` for instructions, and `_tools/release.sh` for the script itself. This script: 1. sanity-checks the various version tags; 2. triggers a Plugin build; 3. flags the new version as pre-release; 4. tags the version in Git; 5. creates a local working copy of the SVN repo; 6. copies the new release to the local `trunk/` (whilst keeping the ‘Stable Tag’ field in `readme.txt` pointing to the previous stable version); 7. copies the commit message from the changelog in `readme.txt`; and 8. (if a flag is set) commits the changes to the remote `trunk/`. Pushing out a new release must still be done manually, once `trunk/` is tested and working. To do so, check out a local copy of `trunk/` and: 1. update the ‘Stable Tag’ field in `trunk/readme.txt` to the new version; 2. update the ‘Version’ field in the comment header of `trunk/footnotes.php` to the new version; 3. remove the ‘p’ from the end of the ‘version’ tag in the `getInfo()` function at the bottom of `js/wsiwyg-editor.js`; 4. copy a new tag for the release from `trunk/` (`svn cp trunk tags/<version number>`); and 5. commit your changes (`svn ci -m "Release version <version number>"`). The WP Plugin Directory will automatically parse the ‘Stable Tag’ field in `trunk/readme.txt`, and inform users that a new version is available. At various stages user input is required to validate information. This is not ready for automation with GitHub Actions, but is a useful step on the way — see [this piece](https://blog.danslimmon.com/2019/07/15/do-nothing-scripting-the-key-to-gradual-automation/) for more info. Unless a `-c` flag is passed (e.g., by running `composer run release:commit`) no changes will take place on the remote SVN repo. If you want to test this out on a branch other than `main`, uncomment lines 31 & 52 of the script. Version checking enforces the versioning rules stated [here](https://github.com/markcheret/footnotes/wiki/Versioning). **NB: I have not tested the `-c` mode yet, as I wanted people will more familiarity with the SVN to have a look at it before I risked making any changes and blowing everything up.** Co-authored-by: pewgeuges <73141620+pewgeuges@users.noreply.github.com>
2021-03-17 17:46:21 +00:00
2021-04-14 22:21:01 +00:00
Automated release deployments will be introduced soon.
2021-04-14 22:21:01 +00:00
### Building
Automatically generate new releases (#59) * Adapt after the 2.5.9d1 accident. * Corrections to changelog. * Also added @‌revision and @‌timestamp PHPDOC tags @‌revision and @‌timestamp used for SVN refs. Full enumeration of added custom PHPDOC tags: @‌accountable, @‌bib, @‌biblio, @‌callback, @‌commit, @‌committer, @‌contributor, @‌courtesy, @‌date, @‌datetime, @‌lastmodified, @‌modified, @‌publisher, @‌reporter, @‌revision, @‌timestamp, @‌user.Some tags like @‌reporter and @‌contributor are more used than others. * Readme header upgrade. * Create deploy-to-wordpress.org.yml * Add distignore * Comment out `build` command, replace npm with composer * Remove placeholder comments * Add build commands * Fix typo * Fix version number bug * Make zip without top-level directory * Append tag name to plugin zip * Clean up a bit * Rename workflow config * Fix upload paths * Append tag name to artifact * Fix paths * Revert path fix * Try again * Add wplm-config.xml to buildfiles * Fix indentation * Rename development/csscat.sh to css/csscat.sh * Rename development/customized-documentation-schema.txt to customized-documentation-schema.txt * Rename development/customized-template-stack.txt to customized-template-stack.txt * Version number related fixes before pull request. * Move csscat script to tools dir * Rename csscat * Refactor script * Update customized-documentation-schema.txt * Replace empty lines in help output * Escape empty lines. * Delete 3 items from `.distignore` As mentioned, CONTRIBUTING.md and README.md should be included in distributions. - As an invitation to the Community. - As a tangible proof of goodwill after the 2.5.9d1 accident. Also SECURITY.md so Footnotes users see that we’re concerned, and can reach out without transiting via GitHub. * Include CONTRIBUTING.md README.md SECURITY.md * Update sync w/ 5.7 tested. * Update * Update composerfiles Co-authored-by: pewgeuges <73141620+pewgeuges@users.noreply.github.com>
2021-03-12 17:53:49 +00:00
2021-04-14 22:21:01 +00:00
1. Run `_tools/build-stylesheets.sh -c` to concatenate stylesheets;
1. manually minify the output files in `css/tmp/`, saving them as `.min.css` files:
* the intention is to replace this with automated minification, meaning that
Automatically generate new releases (#59) * Adapt after the 2.5.9d1 accident. * Corrections to changelog. * Also added @‌revision and @‌timestamp PHPDOC tags @‌revision and @‌timestamp used for SVN refs. Full enumeration of added custom PHPDOC tags: @‌accountable, @‌bib, @‌biblio, @‌callback, @‌commit, @‌committer, @‌contributor, @‌courtesy, @‌date, @‌datetime, @‌lastmodified, @‌modified, @‌publisher, @‌reporter, @‌revision, @‌timestamp, @‌user.Some tags like @‌reporter and @‌contributor are more used than others. * Readme header upgrade. * Create deploy-to-wordpress.org.yml * Add distignore * Comment out `build` command, replace npm with composer * Remove placeholder comments * Add build commands * Fix typo * Fix version number bug * Make zip without top-level directory * Append tag name to plugin zip * Clean up a bit * Rename workflow config * Fix upload paths * Append tag name to artifact * Fix paths * Revert path fix * Try again * Add wplm-config.xml to buildfiles * Fix indentation * Rename development/csscat.sh to css/csscat.sh * Rename development/customized-documentation-schema.txt to customized-documentation-schema.txt * Rename development/customized-template-stack.txt to customized-template-stack.txt * Version number related fixes before pull request. * Move csscat script to tools dir * Rename csscat * Refactor script * Update customized-documentation-schema.txt * Replace empty lines in help output * Escape empty lines. * Delete 3 items from `.distignore` As mentioned, CONTRIBUTING.md and README.md should be included in distributions. - As an invitation to the Community. - As a tangible proof of goodwill after the 2.5.9d1 accident. Also SECURITY.md so Footnotes users see that we’re concerned, and can reach out without transiting via GitHub. * Include CONTRIBUTING.md README.md SECURITY.md * Update sync w/ 5.7 tested. * Update * Update composerfiles Co-authored-by: pewgeuges <73141620+pewgeuges@users.noreply.github.com>
2021-03-12 17:53:49 +00:00
all of these steps can be rolled into a single `build` command.
2021-04-14 22:21:01 +00:00
1. run `_tools/build-stylesheets.sh -d` to deploy the minified files to `dist/`:
* **this will delete any existing `dist/` folder!**
2021-04-14 22:21:01 +00:00
1. run `composer run build` to move over the remaining files to `dist/`:
* currently, the files to include in a distribution are hard-coded in
2021-04-14 22:21:01 +00:00
`_tools/build.sh`; but
* the intention is to replace this with a proper parsing of the `.distignore`
2021-04-14 22:21:01 +00:00
file
### Releasing
1. Ensure that you have configured your Git config. with SVN credentials;
1. run the above [build](#building) commands; and
1. run `composer run release` and follow the prompts.
2021-04-14 22:21:01 +00:00
## Testing
Automated testing will be introduced soon.
Automatically generate new releases (#59) * Adapt after the 2.5.9d1 accident. * Corrections to changelog. * Also added @‌revision and @‌timestamp PHPDOC tags @‌revision and @‌timestamp used for SVN refs. Full enumeration of added custom PHPDOC tags: @‌accountable, @‌bib, @‌biblio, @‌callback, @‌commit, @‌committer, @‌contributor, @‌courtesy, @‌date, @‌datetime, @‌lastmodified, @‌modified, @‌publisher, @‌reporter, @‌revision, @‌timestamp, @‌user.Some tags like @‌reporter and @‌contributor are more used than others. * Readme header upgrade. * Create deploy-to-wordpress.org.yml * Add distignore * Comment out `build` command, replace npm with composer * Remove placeholder comments * Add build commands * Fix typo * Fix version number bug * Make zip without top-level directory * Append tag name to plugin zip * Clean up a bit * Rename workflow config * Fix upload paths * Append tag name to artifact * Fix paths * Revert path fix * Try again * Add wplm-config.xml to buildfiles * Fix indentation * Rename development/csscat.sh to css/csscat.sh * Rename development/customized-documentation-schema.txt to customized-documentation-schema.txt * Rename development/customized-template-stack.txt to customized-template-stack.txt * Version number related fixes before pull request. * Move csscat script to tools dir * Rename csscat * Refactor script * Update customized-documentation-schema.txt * Replace empty lines in help output * Escape empty lines. * Delete 3 items from `.distignore` As mentioned, CONTRIBUTING.md and README.md should be included in distributions. - As an invitation to the Community. - As a tangible proof of goodwill after the 2.5.9d1 accident. Also SECURITY.md so Footnotes users see that we’re concerned, and can reach out without transiting via GitHub. * Include CONTRIBUTING.md README.md SECURITY.md * Update sync w/ 5.7 tested. * Update * Update composerfiles Co-authored-by: pewgeuges <73141620+pewgeuges@users.noreply.github.com>
2021-03-12 17:53:49 +00:00
2021-04-14 22:21:01 +00:00
## Code Formatting
This repo. uses pre-commit code formatting and linting on all staged files.
2021-04-14 22:21:01 +00:00
This ensures that only style-conformant code can be committed.
The individual commands can also be called manually:
* Run `composer run format` to run all format commands.
* Run `composer run format:fix` to attempt to automatically fix all formatter warnings
and errors.
* Run `composer run lint` to run all linting commands.
* Run `composer run lint:fix` to attempt to automatically fix all linter warnings
and errors.
2021-04-14 22:21:01 +00:00
### PHP Code
2021-04-14 22:21:01 +00:00
PHP code must follow the [WordPress PHP Coding Standards][wpcs-php].
2021-02-20 19:18:41 +00:00
2021-04-14 22:21:01 +00:00
1. Run `composer run lint:php` to lint all JS/TS files with [PHP CodeSniffer][phpcs]
1. Run `composer run lint:php:fix` to attempt to automatically fix warnings and
2021-04-14 22:21:01 +00:00
errors with the PHP Code Beautifier and Formatter.
### JavaScript Code
2021-02-20 19:18:41 +00:00
2021-04-14 22:21:01 +00:00
JavaScript code must follow the [WordPress JavaScript Coding Standards][wpcs-js].
2021-02-20 19:18:41 +00:00
* Run `composer run format:js` to format all JS files with [Prettier][prettier].
* Run `composer run format:js:fix` to attempt to automatically fix warnings and errors.
* Run `composer run lint:js` to lint all JS files with [ESLint][eslint].
* Run `composer run lint:js:fix` to attempt to automatically fix warnings and errors.
Prettier configuration settings are found in `.prettierrc`.
ESLint configuration settings are found in `.eslintrc.js`. File ignore rules are
found in `.eslintignore`.
2021-04-14 22:21:01 +00:00
### CSS Stylesheets
2021-02-20 19:18:41 +00:00
2021-04-14 22:21:01 +00:00
JavaScript code must follow the [WordPress CSS Coding Standards][wpcs-css].
2021-02-20 19:18:41 +00:00
* Run `composer run lint:css` to format all CSS files with [stylelint][stylelint].
* Run `npcomposerm run lint:css:fix` to attempt to automatically fix warnings and
errors.
stylelint configuration settings are found in `.stylelint.json`.
2021-02-20 19:18:41 +00:00
2021-04-14 22:21:01 +00:00
## Documentation
Run `composer run docs` to automatically generate HTML documentation with
2021-04-14 22:21:01 +00:00
[phpDocumentor][phpdocumentor].
View the current docs [here][footnotes-docs].
2021-02-20 19:18:41 +00:00
## Acknowledgements
Huge thanks to every **footnotes user**, contributor, bug reporter, feature
2021-04-14 22:21:01 +00:00
requester and fan!
## License
This project is licensed under the [GNU GPL v3][gpl-v3].
## Contact Information
2021-04-14 22:21:01 +00:00
| Name | Link(s) |
|---------------|-----------------------|
|Mark Cheret | [Email][mcheret] |
2021-04-14 22:21:01 +00:00
[wpmudev]: http://premium.wpmudev.org/blog/12-surprisingly-useful-wordpress-plugins-you-dont-know-about/
[php]: https://www.php.net/
[contributing]: https://github.com/markcheret/footnotes/blob/main/CONTRIBUTING.md
[vvv]: https://varyingvagrantvagrants.org/
[composer]: https://getcomposer.org/download/
2021-04-15 14:03:09 +00:00
[npm]: https://www.npmjs.com/
2021-04-14 22:21:01 +00:00
[wpcs-php]: https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/
[phpcs]: https://github.com/squizlabs/PHP_CodeSniffer
[wpcs-js]: https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/
[wpcs-css]: https://developer.wordpress.org/coding-standards/wordpress-coding-standards/css/
[prettier]: https://prettier.io/
[eslint]: https://eslint.org/
[stylelint]: https://stylelint.io/
2021-04-14 22:21:01 +00:00
[phpdocumentor]: https://phpdoc.org/
[footnotes-docs]: https://markcheret.github.io/footnotes/
[gpl-v3]: https://www.gnu.org/licenses/gpl-3.0.en.html
[mcheret]: mailto:mark@cheret.de