Introduction
The project aims at creating and deploying a user friendly, interactive and accessible website for PEcAn Project.
PEcAn Project's website consisted of html pages, bookdown and pkgdown pages being rendered separately. In this project, all separate sections have been integrated as a consistent, modern website with elegant UI with the help of Docusaurus 2, a static site generator. This project has been created as a part of GSoC'21.
Useful Links
- Github Repository- https://github.com/PecanProject/web
- Hosted Link- https://pecanproject.github.io/web/
- Documentation- https://github.com/PecanProject/web/blob/main/README.md
Preparations
After my proposal was selected for the project I started interacting with the mentors and asked them about their expectation about design. I also studied the codebase of the existing website. Since I was familiar with ReactJs, I found it much better to have a static site generator for the project. I studied the official docusaurus docs and got familiar with its ecosystem.
Using figma I prepared wireframes for the website. After the first GSoC meeting, I got valuable suggestions from the mentors, which were used to improvise the designs and development of the working model of website began.
Coding Period
To develop the working model on the website it was required to keep in mind the best practices and modular design, so that changes could be made easily in the future. I have tried to maintain this approach. In this period following goals have been accomplished:
- Revamped the website and converted it into a ReactJs based single page application.
- Added a blog for posting blogs.
- Integrated PEcAn's documentation as part of the website.
- Automated build process of the website with the help of GitHub actions. This helps to deploy the website automatically to GitHub pages, as soon as changes are pushed.
- Documented steps for PEcAn team to add and modify content.
Challenges
Since the documentation is maintained as bookdown specific Rmarkdown format, it is difficult to parse it using docusaurus's native parser, which supports markdown. The bookdown doesn't offer a native way of converting into md, with relative directory structure to reference different files. I tried converting each Rmd file into md, one by one using RStudio's built-in knit function, but it wasn't feasible. The only optimal solution seemed was temporarily editing MakeFile, but it couldn't achieve desired results.
This is also the exact challenge with tutorials section.
Next Steps
At present we have an iframe which helps us load the documentation inside the website, though it looks like a part of the website, it is the website which is being rendered by bookdown. It can be found on this repo-
https://github.com/PecanProject/pecan-documentation. An example of how this is achieved is shown in below codeblock-
<Layout title="Develop" style={{ height: "100%" }}>
<Foot>
<body className="documentation"></body>
</Foot>
<iframe
src="https://pecanproject.github.io/pecan-documentation/develop/"
style={{ border: "none" }}
width="100%"
height="100%"
allowFullScreen
id="iFrame1"
>
<p>
<a href="/en-US/docs/Glossary">
Fallback link for browsers that don't support iframes
</a>
</p>
</iframe>
</Layout>
The main issue is that if we had docs already natively on the repository, they would have been much faster to load and would have offered the users a much better experience. So it is essential and recommended to figure out a way for achieving this. Further priorities would be-
- Adding the tutorials section
- Adding a search bar that uses scraping to find matches all across website.
Screenshots
Pull Requests Made
| Pull Request | Status |
|---|---|
| Pull Request 1 | Merged |
| Pull Request 2 | Merged |
| Pull Request 3 | Merged |
| Pull Request 4 | Merged |
| Pull Request 5 | Merged |
| Pull Request 6 | Merged |
| Pull Request 7 | Merged |
| Pull Request 8 | Open |
Acknowledgements
Finally, I'd like to say that this summer of 2021 has been the most amazing experience I've ever had. I learnt a lot of technical and non technical skills. Dlebauer and ImPrakher have been awesome mentors and their feedback and suggestions were a key to accomplishing the project.
Top comments (0)