PlacetoPay Docs

This documentation project contains all the information necessary to perform integrations with the PlacetoPay Checkout and PlacetoPay Gateway API services.

This project is made with the Tailwind UI Protocol template which was built using Tailwind CSS and Next.js.

Getting started

To get started with this template, first install the npm dependencies:

npm install

Next, run the development server:

npm run dev

Finally, open http://localhost:3000 in your browser to view the website.

Customizing

Theory Page

These pages are made in MDX syntax and can be found inside the "pages" folder. The file format is mdx and the file name and location path from the "pages" folder is the path you will have in the application.

Steps to add a new entry

Create the file with the name and location corresponding to the path you want it to have in the application. Then, so http://localhost:3000/my-folder/my-file corresponds to a file called my-file.mdx inside the my-folder folder which is in the path src/pages.
Write the content of your file following the MDX syntax.
- the <title /> of the page will be the first header that has been declared in the file.
- Second level headers (html: h2 / mdx: ##) autogenerate URL fragments or hashes which must be modified by adding {{ id: 'your-has-here' }} after the header text to be consistent with the language change.
- Being MDX format, HTML tags are completely accepted and their functionality is the same as in a .html file.
- The images used must be inside the public/ folder, here they can be added directly to the root of the folder or create subfolders to have better order.
To add the route to the navigation panel you must follow the steps in this section.
Make sure you have saved all the changes made and enter the new route that was created.

Steps to modify an entry

Determine the path of the file to edit based on the URL path. So if the URL is http://localhost:3000/my-folder/my-file the file is located in src/pages/my-folder/my-file.
Open the file in your trusted code editor and modify it following the instructions in the previous section.
Save the file and see the changes in the browser

API page

Steps to add a new endpoint

Identify if it should go under the scope of gateway or checkout.
Depending on the corresponding scope, the YML file located within src/assets/YOUR_SCOPE/es.yml must be opened in your code editor.
Following the openapi v3.1 specification add the new endpoint to the file.
Repeat the process in the src/assets/YOUR_SCOPE/en.yml file with the English language.
Open or create the file where you want this documentation to be viewed. These files must be within the corresponding scope (checkout / gateway) and within the api-reference subfolder.
Copy the content of the file located in stubs/apiReference.mdx.stub and paste it into the previously created file.
Replace the values corresponding to the endpoint that you created in step 3 and declare the rest of the information you need on the page, the information that you are not going to use, remove it so that it does not appear in the browser.
Open the route you just added in the browser and enjoy the results!

Cases to take into consideration

Cyclical dependencies: As developers we are characterized by avoiding duplicating code as much as possible, but many times this can result in a cyclic dependency if we are not careful with its use. Well, when building a new endpoint it may be possible to generate cyclic dependencies since these allow references to other schemas to avoid duplicating the same block of code. When doing this, which is completely valid, the main care must be taken not to create a cyclic reference (a schema that refers to another schema and that refers to the first one) since if this happens, the application breaks and does not present a clear error, causing a crash dump due to overuse.

Navigation

The paths are auto-generated by the name and location of the files within the src/pages folder.

Step to add new item to sidebar navigation

Open the src/constants/navigations.
Add the new entry to the correct constant by following:
- The title property is the text that will appear in the sidebar navigation
- The href property is the path that the browser will direct to when the user selects the element in the sidebar
The process must be repeated for each language constant.

Translations

In the project, the translations are file-based, so when you want to translate a path to English you must create the same file path within the src/pages/en folder and rewrite all the content in English.

This applies to theory pages and API pages.

How to contribute to git

Steps to generate or modify a new entry

Creates a new branch from develop following the git flow convention it should be called with the prefix Feature/, Refactor/ or Fix/.
Make your changes in that branch and commit progressively with your changes to avoid problems if a revert is necessary.
Push your changes to the repository and create a new Pull request.
Modify the description of your Pull Request with a brief explanation of the change and add Eduardo Gúzman as a Reviewer.
Notify by internal message about the existence of the PR to speed up review, merger and deployment times.
Wait for the change notice to be displayed and check in production that your changes are just as you expect.

License

This site template is a commercial product and is licensed under the Tailwind UI license.

Learn more

To learn more about the technologies used in this site template, see the following resources:

Tailwind CSS - the official Tailwind CSS documentation
Next.js - the official Next.js documentation
Headless UI - the official Headless UI documentation
Framer Motion - the official Framer Motion documentation
MDX - the official MDX documentation
Algolia Autocomplete - the official Algolia Autocomplete documentation
FlexSearch - the official FlexSearch documentation
Zustand - the official Zustand documentation

mascam97/placetopay-docs