feat(docussaurus): upgrade Docussaurus and document development procedures #11
Conversation
lucaaamaral
changed the title
lucaaamaral
force-pushed
the
chore/evaluate-conrado-pr
branch
from
670f346 to
5635f10
Compare
|
Commenting just another task to be done in this PR: need to check the new configuration of docusaurus for the "current" version docs (probably |
docusaurus/docusaurus.config.js
Outdated
| // Please change this to your repo. | ||
| // Remove this to remove the "edit this page" links. | ||
| editUrl: | ||
| 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/', |
There was a problem hiding this comment.
Could we have this 'edit this page' pointing to this repository?
|
Let's bring CI here to be able to merge. I saw you have them done already. |
Done |
| cd docusaurus/docs | ||
| MODIFIED_DOCS=$(find . -type f \( -name "*.md" -o -name "*.mdx" \) ! -path "versioned_docs/*") | ||
| else | ||
| BASE_REF="${GITHUB_BASE_REF:-origin/main}" |
There was a problem hiding this comment.
Set the variables that may be changed based on input at the beginning of the script so it is easy to spot and understand.
There was a problem hiding this comment.
to use the extensions in an array need to construct the -name conditions dynamically, ill try to address to that
There was a problem hiding this comment.
Defined as global states (for now) is your proposition to define the vars in the jobs ENV and insert them in the script via the args?
| CHECKED_FILES=$((CHECKED_FILES + 1)) | ||
|
|
||
| filename=$(basename "$file") | ||
| expected_id=$(echo "$filename" | sed 's/\.[^.]*$//') # Remove extension |
There was a problem hiding this comment.
You can use that to remove the extention: expected_id=$(basename "$file" .txt)
https://stackoverflow.com/questions/3362920/get-just-the-filename-from-a-path-in-a-bash-script
There was a problem hiding this comment.
Is possible to add the regex in the basename command?
|
Regarding the broken link issue at the build process: There's no Same happens at:
|
|
Other missing files:
|
|
Current error log of Build process: |
lucaaamaral
force-pushed
the
chore/evaluate-conrado-pr
branch
from
3f7871c to
046d685
Compare
Signed-off-by: Lucas Amaral <lucaaamaral@gmail.com>
Signed-off-by: Lucas Amaral <lucaaamaral@gmail.com>
Changing the docusaurus version from costum to the standart open source release Signed-off-by: conradogobato <conradogob07@gmail.com>
lucaaamaral
force-pushed
the
chore/evaluate-conrado-pr
branch
from
046d685 to
9d27024
Compare
…updating dependencies and configurations Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>
lucaaamaral
force-pushed
the
chore/evaluate-conrado-pr
branch
from
9d27024 to
ea2d7de
Compare
…mepage layout and styles Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>
Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>
Remove CHANGELOG and NOTES files, clean up Dockerfile and docker-compose, and update docusaurus configuration Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>
* chore: enhance CI workflows with new scripts for documentation checks and remove obsolete reference check Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * chore: update documentation CI workflow for improved checks and formatting Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * debug: Run everything for testing Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * testing: path filter step dependency removal Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * fix: grant execute permissions to workflow scripts for consistency checks Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * fix: update workflow scripts for improved debugging and path handling Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * fix: Convert format to standad POSIX and streamline with dos2unix dependency and consolidating permission grants Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * fix: Update workflow scripts to change directory for dependency installation and improve script execution consistency Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> --------- Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>
…cripts Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>
Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>
…tion, Update Build & Log workflow Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>
Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>
…nally Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>
…proved build command Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>
Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>
…improve clarity - Updated links in alerts_troubleshooting.md, alert.md, and other files to include the correct .md extension for consistency. - Adjusted API endpoint formatting in proposals and howtos for better readability. - Ensured all references to configuration steps and troubleshooting guides are accurate and up-to-date. Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>
|
In order to make a rebase, I had to:
I noticed that we have two package.json - maintain only one for deployment. |
Why? The configurations of the previous version of the file (regarding the latest version of Docusaurus) are now lost?
The information that was "removed" was mostly due to the update of the Docusaurus version, and also by Conrado's initial changes
The original (from
It seems, as the above comments that I've posted that not only some images were "lost" but also some versioned documents, also due to Conrado changes... E.g.
The second [cause]: Error: Docusaurus was unable to resolve the "@docusaurus/theme-mermaid" theme. Make sure one of the following packages are installed:
- @docusaurus/theme-mermaid
- @docusaurus/docusaurus-theme-theme-mermaidAt Build and Log workflow |
|
@lucaaamaral as discussed aat todays metting, moved the readmes folder and placed a symlink, the references for the assets should now be updated as pointed by Build and Log and URL Check |
I made a rebase bringing the changes of this file to a point prior to your changes. It was messy, probably not the best way to do it when thinking about the git history. Conrado's PR removed the previous configuration file, instead of renaming and adjusting its contents.
I just added the mermaid under the
Let's sove in a posterior PR.
Let's solve this in a different PR. |
Please, revert the last commit and open a new branch and PR for these changes. I cannot evaluate new features and big changes in this PR anymore; it is already too big. Let's focus -> this PR is about Docussaurus upgrade. Anything out of this scope, please create a new branch and open a separate PR. Example of things outside the scope:
|
|
Ok @lucaaamaral , i'll address to this requests on friday, as it's a holiday |
Signed-off-by: Lucas Amaral <lucaaamaral@gmail.com>
Signed-off-by: Lucas Amaral <lucaaamaral@gmail.com>
lucaaamaral
force-pushed
the
chore/evaluate-conrado-pr
branch
from
de852d9 to
30fbca4
Compare
Signed-off-by: Lucas Amaral <lucaaamaral@gmail.com>
Signed-off-by: Lucas Amaral <lucaaamaral@gmail.com>
docusaurus/.dockerignore
Outdated
| **/package.json | ||
| **/package-lock.json |
There was a problem hiding this comment.
If the yarn.lock is ignored so should the package-lock.json, they're both the "same" file, only created by different package managers
| #================================================================== | ||
| # Production deployment with Caddy automatic SSL/TLS | ||
| #================================================================== | ||
| FROM caddy:2-alpine AS caddy | ||
| COPY --from=prod /opt/docusaurus/Caddyfile /etc/caddy/Caddyfile | ||
| COPY --from=prod /opt/docusaurus/build /var/docusaurus |
There was a problem hiding this comment.
There's no need for a Caddy implementation as the GH Pages handles the deployment and certificates, unless will be hosted in a dedicated server, but as I remember @lucasgonze said it would continue to be in GH Pages
| ports: | ||
| - "3000:3000" | ||
| - "3000:3000" |
docusaurus/docker-compose.yml
Outdated
| caddy: # TODO: fix issues | ||
| build: | ||
| context: . | ||
| target: caddy | ||
| container_name: docusaurus_caddy | ||
| ports: | ||
| - "80:80" | ||
| - "443:443" | ||
| environment: | ||
| - NODE_ENV=production | ||
| - DOCUSAURUS_DOMAIN=docusaurus.example | ||
| - DOCUSAURUS_EMAIL=letsencrypt@docusaurus.example | ||
| volumes: | ||
| - caddy_data:/data | ||
| - caddy_config:/config | ||
|
|
||
| volumes: | ||
| caddy_data: | ||
| caddy_config: |
There was a problem hiding this comment.
Same note as in docusaurus/Dockerfile
| @@ -4,7 +4,7 @@ | |||
| "private": true, | |||
| "scripts": { | |||
| "docusaurus": "docusaurus", | |||
| "start": "docusaurus start", | |||
| "start": "docusaurus start --host 0.0.0.0", | |||
There was a problem hiding this comment.
This will block local testing, some files are created with local commands such as translation files. This means that if the command is only called inside a Docker container the updated files will be located inside or the temporary container or at the volumes. Will be needed manual work to copy the local files (e.g. translation copies) to the local repo.
Changes Summary
This PR refers to #9.
The first commit was a cherry-pick from the same commit (03377f6) made by Conrado. The other changes are listed below.
Removed
docusaurus/blog/as discussed in Slack, and as the existing text is not relevant to the project, it has been removed.docusaurus/README.mdas it is already present information duplicated with another files likedocs/howtos/documentation_development.md.docusaurus/package-lock.jsonas the local development should be done withyarn.HomepageFeaturescomponents as was only being imported and not used.Added
docusaurus/docs/howtos/documentation_development.mdas to give instructions on how to develop documentation.docusaurus/docker.package.jsonto include the dependencies needed to build the containers.Updated
docusaurus/.dockerignorerefenrencing the the other JS modules that are not needed when building the container.docusaurus/package.jsonto include the latest versions of the dependencies.docusaurus/Dockerfilethe the new instructions to build the containers of Development and Production.index.jsto include the new components and remove the unused ones.Test Plan
Basic Docusaurus build tests
Additional Information
Security Considerations
Meeting scheduled to 27/03/2025.