diff --git a/.github/workflows/php.yml b/.github/workflows/php.yml index 6dcf060..619c495 100644 --- a/.github/workflows/php.yml +++ b/.github/workflows/php.yml @@ -27,10 +27,11 @@ jobs: ${{ runner.os }}-php- - name: Install dependencies - run: composer install --prefer-dist --no-progress + run: composer install --prefer-dist --no-progress --ignore-platform-reqs - # Add a test script to composer.json, for instance: "test": "vendor/bin/phpunit" - # Docs: https://getcomposer.org/doc/articles/scripts.md + - name: Lint PHP code + run: composer run lint:php + # TODO: Add tests # - name: Run test suite # run: composer run-script test diff --git a/README.md b/README.md index 99d11c2..fc87f7f 100644 --- a/README.md +++ b/README.md @@ -2,76 +2,138 @@ # footnotes -## Description +Featured on [wpmudev][wpmudev] — cheers for the review, folks! -Featured on [wpmudev](http://premium.wpmudev.org/blog/12-surprisingly-useful-wordpress-plugins-you-dont-know-about/) — cheers for the review, folks! +**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 +footnotes will be displayed. -**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 footnotes are being displayed. +**footnotes** gives you the ability to display well-formatted footnotes on your +WordPress Pages and Posts — those footnotes we know from offline publishing. -**footnotes** gives you the ability to display well-formatted footnotes on your WordPress Pages and Posts — those footnotes we know from offline publishing. +## Table of Contents + +* [Features](#features) +* [Getting Started](#getting-started) +* [Deploying](#deploying) +* [Testing](#testing) +* [Code Formatting](#code-formatting) +* [Documentation](#documentation) +* [Acknowledgments](#acknowledgements) +* [License](#license) +* [Contact Information](#contact-information) + +## Features + +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 + rules; and +- editor buttons for easily adding shortcode tags. ## Getting Started -1. Read the contributing guidelines -1. Clone this repository (`git clone git@github.com:markcheret/footnotes.git`) - - We recommend that you use [VVV](https://varyingvagrantvagrants.org/) for your local testing environment -1. Install [Composer](https://getcomposer.org/download/), if you don't have it already -1. Install dependencies (`composer install`) - - You will have to install `php-mbstring` manually if you do not already have it. +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. +1. install [Composer][composer], if you don't have it already; and +1. install all dependencies (`composer install`): + - you will have to install `php-mbstring` manually if you do not already + have it. + +## Deploying + +Automated release deployments will be introduced soon. + +### Building + +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 + all of these steps can be rolled into a single `build` command. +1. run `_tools/build-stylesheets.sh -d` to deploy the minified files to `dist/`: + - **this will delete any existing `dist/` folder!** +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 + `_tools/build.sh`; but + - the intention is to replace this with a proper parsing of the `.distignore` + 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. + +## Testing + +Automated testing will be introduced soon. ## Code Formatting -1. Run `composer run lint-php` to lint all PHP files -1. Run `composer run lint-php:fix` to attempt to automatically fix errors and warnings +This repo. uses pre-commit code formatting and linting on all staged files. +This ensures that only style-conformant code can be committed. -## Releasing +The individual commands used by the pre-commit hook can also be called manually: -1. Run `composer run release` +### PHP Code -## Building +PHP code must follow the [WordPress PHP Coding Standards][wpcs-php]. -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 - all of these steps can be rolled into a single `build` command. -1. Run `_tools/build-stylesheets.sh -d` to deploy the minified files to `dist/` - - **this will delete any existing `dist/` folder** -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 `_tools/build.sh` - - The intention is to replace this with a proper parsing of the `.distignore` file +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 + errors with the PHP Code Beautifier and Formatter. + +### JavaScript Code -## Updating Documentation +JavaScript code must follow the [WordPress JavaScript Coding Standards][wpcs-js]. -1. Run `composer run docs` +Automated linting and formatting will be introduced soon. + +### CSS Stylesheets -## Testing +JavaScript code must follow the [WordPress CSS Coding Standards][wpcs-css]. -Unit tests are TODO. +Automated linting and formatting will be introduced soon. -## Main Features +## Documentation -- Fully customizable **footnotes** start and end shortcodes; -- Styled tooltips supporting hyperlinks display **footnotes** or a dedicated text; -- Responsive *Reference Container* at the end or positioned by shortcode; -- Display the **footnotes** *Reference Container* inside a Widget; -- Wide choice of numbering styles; -- Freely configurable and optional backlink symbol; -- Configure the **footnotes'** appearance by dashboard settings and Custom CSS style rules; -- Button in both the Visual and the Text editor to add shortcodes around selection. +Run `composer run docs` to automatically generate HTML documentation with +[phpDocumentor][phpdocumentor]. -## Example Usage - -These are a few examples of possible ways to delimit footnotes: - -1. Your awesome text`((`with an awesome footnote`))` -2. Your awesome text`[ref]`with an awesome footnote`[/ref]` -3. Your awesome text``with an awesome footnote`` -4. Your awesome text`custom-shortcode`with an awesome footnote`custom-shortcode` - -## Where to get footnotes? - -The current version is available on the [WordPress.org Plugin Directory](https://wordpress.org/plugins/footnotes/). +View the current docs [here][footnotes-docs]. ## Acknowledgements -Huge thanks to every **footnotes user**, contributor, bug reporter, feature requester and fan! +Huge thanks to every **footnotes user**, contributor, bug reporter, feature +requester and fan! + +## License + +This project is licensed under the [GNU GPL v3][gpl-v3]. + +## Contact Information + +| Name | Link(s) | +|---------------|-----------------------| +|Mark Cheret | [Email][mcheret] | + +[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/ +[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/ +[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 diff --git a/composer.json b/composer.json index 4b3354c..f817e43 100644 --- a/composer.json +++ b/composer.json @@ -1,15 +1,15 @@ { "name": "markcheret/footnotes", "description": "footnotes aims to be the all-in-one solution for displaying an automatically-generated list of references on your WordPress Page or Post.", - "license": "GPL-3.0-or-later", + "license": "GPL-3.0-only", "scripts": { "release": "./_tools/release.sh", "release:commit": "composer run release -- -c", "build": "./_tools/build.sh", - "lint-php": "./vendor/bin/phpcs --standard='WordPress' --colors --encoding=utf-8 -n -p --ignore=*/vendor/* ./*.php ./*/*.php ./*/*/*.php", - "lint-php:fix": "./vendor/bin/phpcbf --standard='WordPress' --encoding=utf-8 -p --ignore=*/vendor/* ./*.php ./*/*.php ./*/*/*.php", - "lint-css": "echo TODO", - "lint-js": "echo TODO", + "lint:php": "./vendor/bin/phpcs --standard='WordPress' --colors --encoding=utf-8 -n -p --ignore=*/vendor/* ./*.php ./*/*.php ./*/*/*.php", + "lint:php:fix": "./vendor/bin/phpcbf --standard='WordPress' --encoding=utf-8 -p --ignore=*/vendor/* ./*.php ./*/*.php ./*/*/*.php", + "lint:css": "echo TODO", + "lint:js": "echo TODO", "docs": "./vendor/bin/phpdoc -d . -t ./docs --ignore vendor/", "commit": "./vendor/bin/php-commitizen commit -- ./.php-commitizen.php", "post-install-cmd": "./_tools/setup.sh" diff --git a/composer.lock b/composer.lock index ddd8915..79b7024 100644 --- a/composer.lock +++ b/composer.lock @@ -482,16 +482,16 @@ }, { "name": "laminas/laminas-code", - "version": "4.1.0", + "version": "4.2.0", "source": { "type": "git", "url": "https://github.com/laminas/laminas-code.git", - "reference": "5b553c274b94af3f880cbaaf8fbab047f279a31c" + "reference": "e7e8f8a9c267520051d8026ff1da74823a3d8b97" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/laminas/laminas-code/zipball/5b553c274b94af3f880cbaaf8fbab047f279a31c", - "reference": "5b553c274b94af3f880cbaaf8fbab047f279a31c", + "url": "https://api.github.com/repos/laminas/laminas-code/zipball/e7e8f8a9c267520051d8026ff1da74823a3d8b97", + "reference": "e7e8f8a9c267520051d8026ff1da74823a3d8b97", "shasum": "" }, "require": { @@ -549,7 +549,7 @@ "type": "community_bridge" } ], - "time": "2021-03-27T13:55:31+00:00" + "time": "2021-04-14T22:05:06+00:00" }, { "name": "laminas/laminas-eventmanager",