bb7bfcc2c2
* refactor: Migrate documentation to MkDocs with material theme and improved structure * refactor: docs images hierarchy * refactor: Move screenshots to assets and update paths in Screenshots.md * feat: Convert screenshots to MkDocs content tabs with light/dark theme switching * feat: sync content tabs by label * chore: add light theme with shiori red color * docs: Update index page to match README with concise feature list * docs: Remove Resources section from documentation index * ci: added github workflows * docs: Add section for building documentation in Contribute.md
3 KiB
Contribute
Running the server locally
To run the current development server with the defaults you can run the following command:
make serve
If you want to run the refactored server, you can run the following command:
make run-server
ℹ️ Note: For more information into what the refactored server means, please check this issue: https://github.com/go-shiori/shiori/issues/640
Updating the API documentation
ℹ️ Note: This only applies for the Rest API documentation under the
internal/httpfolder, not the one underinternal/webserver.
If you make any changes to the Rest API endpoints, you need to update the swagger documentation. In order to do that, you need to have installed swag.
Then, run the following command:
make swagger
Updating the frontend styles
The styles that are bundled with Shiori are stored under internal/view/assets/css/style.css and internal/view/assets/css/archive.css and created from the less files under internal/views/assets/less.
If you want to make frontend changes you need to do that under the less files and then compile them to css. In order to do that, you need to have installed bun.
Then, run the following command:
make styles
The style.css/archive.css will be updated and changes needs to be committed to the repository.
Lint the code
In order to lint the code, you need to have installed golangci-lint and swag.
After that, run the following command:
make lint
If any errors are found please fix them before submitting your PR.
Running tests
In order to run the test suite, you need to have running a local instance of MariaDB and PostgreSQL. If you have docker, you can do this by running the following command with the compose file provided:
docker-compose up -d mariadb postgres
After that, provide the SHIORI_TEST_PG_URL and SHIORI_TEST_MYSQL_URL environment variables with the connection string to the databases:
SHIORI_TEST_PG_URL=postgres://shiori:shiori@127.0.0.1:5432/shiori?sslmode=disable
SHIORI_TEST_MYSQL_URL=shiori:shiori@tcp(127.0.0.1:3306)/shiori
Finally, run the tests with the following command:
make unittest
Building the documentation
The documentation is built using MkDocs with the Material theme. For installation instructions, please refer to the MkDocs installation guide.
To preview the documentation locally while making changes, run:
mkdocs serve
This will start a local server at http://127.0.0.1:8000 where you can preview your changes in real-time.
Documentation for production is generated automatically on every release and published using github pages.