A React webapp to publish and study extended content in Markdown format organized in articles and categories and allowing annotations.
Github repository: https://github.com/jesusramirezs/react-studyboard
Please submit bug fixes via pull requests & feedback via issues.
With this app, I intend to develop an example app by using some of the latest trends in real React app (redux, hooks,...) and that, besides fulfilling an educational function, offers an attractive functionality.
When I thought about developing React StudyBoard, I imagined an app where you could publish extensive articles on a particular study topic and organize them into sections or categories, which would be useful for the study. I want this app to be helpful as an educational and informative app not only for simple reading, and for this, It had to allow:
- Using Markdown for more friendly text formatting.
- Keeping a record of what has been read so far.
- To continue reading a text at the last point where it was left.
- To maintain an index of the following readings to be addressed by the student.
- Adapting the characteristics of the text to the reader's preferences (font type, size...)
- Highlighting important text for the reader.
- Adding and organizing annotations (also in Markdown format) to any text within the article.
- Annotations must also support uploaded images (for now to Imgur).
- Being able to add tags to any annotation.
- Editing annotations.
- Displaying the annotations made just by moving the cursor over the text without interrupting the reading flow.
- Quickly access to a list of all the annotations made in reverse chronological order of editing, from any of the articles, and from them, navigate to the point in the article to which they refer.
This is the first version, and later in this article, I will tell you about the next tasks to be tackled in future versions.
To get the frontend running locally:
- Clone this repo
git clone https://github.com/jesusramirezs/react-studyboard.git
yarnto install all required dependencies
- Optional: Edit the config-data.js file with your Firebase credentials and your Imgur API keys
yarn startto start the local server (this project uses create-react-app)
- App should now be running on
The project makes use of the following:
- React Hooks
- React Redux
- React Suite components
- Styled components
- Firebase authentication
The code is reasonably easy to follow and understand. It is divided into pages and components, each of them in a separate folder; I think they are as simple and decoupled as possible so that we do not add excessive levels to the code. The same has been done with different Redux stores.
All contents: sections and articles are stored in two JSON files, easy to maintain and organize: one for categories and one for articles.
The Markdown formatting is applied using the component Markdown-to-jsx, in its version 6.11.4; I must mention that the last version of this package has generated some errors still to be solved.
This component supports different functions for each of the formats, and specific functions have been implemented for rendering (in text-block.component.jsx) :
- list elements
- titles (h1...h6)
The tag-input component is used to enter tags in the annotation form and unique colors have been set aside for three specific tags so that they are visually easy to identify:
All standard status management between components in the app is managed through React-Redux, and all access to the standard status is done through selectors.
Redux stores the most varied information:
- The visible or hidden state of the side panels
- The reading progress point of each article and the last article read.
- All content: articles and categories Content of the reading list
- All text portions highlighted
- User preferences (preferred font and size)
The system uses local storage as user data storage, almost everything stored in Redux except the contents themselves.
So far, this could be enough, but obviously, it has its limitations, and in the next version, the app will probably use Firebase as cloud storage.
An authentication mechanism has been implemented through user password and Google Auth but only for educational purposes and to support the cloud storage and sharing of content and annotations between users in a future version.
I am not a graphic designer, so I have tried to keep the style as simple as possible. To do this, I have used:
- Tachyons CSS as the main style base.
- Styled Components to apply the styles to some of the components.
- React Suite for some particular components: drawer, progress bar.
There are still many points of improvement and evolution in the project:
- Allow highlighting of any word selection, not just whole paragraphs, and allow annotations on them.
- Allow the sharing of notes between different students.
- Allow several tabs to keep reading several articles at once. Perhaps use a splitter in the reading panel to have two or more articles active.
- Improve the management of image uploads to the cloud.
- Add night mode for reading.
- Filter the side panel annotations according to tags. For example: display only "questions" or "re-readings.
- The possibility of publishing your articles (summaries, reflections) and dynamically integrating notes on other articles into the content.
- The possibility to export/import annotations in the JSON file.
EDIT: Dec 19, 2020
Accomplished: Filter the side panel annotations according to tags. For example: display only "questions" or "re-readings.
Accomplished: Allow highlighting of any word selection, not just whole paragraphs.
Accomplished: Improved behaviour os scroll restoration mechanism.
- PropTypes for type verification.
- Improve the naming of some components.
- Improve the communication mechanism between components, e.g., Article and Annotation Form.
- Use a database system for storage of items (instead of JSON files), statuses, and annotations. Perhaps based on Apollo and GraphQL.
- Integrate a complete testing system into the project. In-depth performance review.
All texts have benn generated using https://www.blindtextgenerator.com/
All images come from the initiative Open Access from The Metropolitan Museum of Art:
Thanks for reading this article. Any feedback will be greatly appreciated.