Example of README.md files to be used as template
The live link can be found here
In this section, you will include one or two paragraphs providing an overview of your project. Essentially, this part is your sales pitch. At this stage, you should have a name for your project so use it! Don’t introduce the project as a Portfolio project for the diploma. In this section, describe what the project hopes to accomplish, who it is intended to target and how it will be useful to the target audience.
For example; Love Running is a site that hopes to help keep people motivated to meet up for runs on a regular basis in Dublin, Ireland. The site will be targeted toward runners who are looking for a way to socialise and keep themselves fit. Love Running will be useful for runners to see exactly when and where they should be to join the running club.
- Reading list fullstack (nodeJS, express, React)
- Table of contents
- User Experience (UX)
- Design
- Features
- Testing
- Deployment
- Bugs
- Pending
- Technologies Used
- Development
- Deploy
- Contribution
- Other General Project Advice
- Credits
- Acknowledgments
- Extra references to create the README file
Table of contents generated with markdown-toc
Colour palette from Coolors
A warning message will appear to the user when inaccurate or empty data is entered into a form, identifying the specific field that caused the issue. This prevents the form from being submitted until the issue is resolved, ensuring that only accurate and complete data is processed.
In this section, you should go over the different parts of your project, and describe each in a sentence or so. You will need to explain what value each of the features provides for the user, focusing on who this website is for, what it is that they want to achieve and how your project is the best way to help them achieve these things.
-
Navigation Bar
- Featured on all three pages, the full responsive navigation bar includes links to the Logo, Home page, Gallery and Sign Up page and is identical in each page to allow for easy navigation.
- This section will allow the user to easily navigate from page to page across all devices without having to revert back to the previous page via the ‘back’ button.
-
The landing page image
- The landing includes a photograph with text overlay to allow the user to see exactly which location this site would be applicable to.
- This section introduces the user to Love Running with an eye catching animation to grab their attention
-
Club Ethos Section
- The club ethos section will allow the user to see the benefits of joining the Love Running meetups, as well as the benefits of running overall.
- This user will see the value of signing up for the Love Running meetups. This should encourage the user to consider running as their form of exercise.
-
Meetup Times section
- This section will allow the user to see exactly when the meetups will happen, where they will be located and how long the run will be in kilometers.
- This section will be updated as these times change to keep the user up to date.
-
The Footer
- The footer section includes links to the relevant social media sites for Love Running. The links will open to a new tab to allow easy navigation for the user.
- The footer is valuable to the user as it encourages them to keep connected via social media
-
Gallery
- The gallery will provide the user with supporting images to see what the meet ups look like.
- This section is valuable to the user as they will be able to easily identify the types of events the organisation puts together.
-
The Sign Up Page
- This page will allow the user to get signed up to Love Running to start their running journey with the community. The user will be able specify if they would like to take part in road, trail or both types of running. The user will be asked to submit their full name and email address.
For some/all of your features, you may choose to reference the specific project files that implement them.
In addition, you may also use this section to discuss plans for additional features to be implemented in the future:
- Another feature idea
In this section, you need to convince the assessor that you have conducted enough testing to legitimately believe that the site works well. Essentially, in this part you will want to go over all of your project’s features and ensure that they all work as intended, with the project providing an easy and straightforward way for the users to achieve their goals.
In addition, you should mention in this section how your project looks and works on different browsers and screen sizes.
You should also mention in this section any interesting bugs or problems you discovered during your testing, even if you haven't addressed them yet.
If this section grows too long, you may want to split it off into a separate file and link to it from here.
- HTML
- No errors were returned when passing through the official W3C validator
- CSS
- No errors were found when passing through the official (Jigsaw) validator
You will need to mention unfixed bugs and why they were not fixed. This section should include shortcomings of the frameworks or technologies used. Although time can be a big variable to consider, paucity of time and difficulty understanding implementation is not a valid reason to leave bugs unfixed.
This section should describe the process you went through to deploy the project to a hosting platform (e.g. GitHub)
- The site was deployed to GitHub pages. The steps to deploy are as follows:
- In the GitHub repository, navigate to the Settings tab
- From the source section drop-down menu, select the Master Branch
- Once the master branch has been selected, the page will be automatically refreshed with a detailed ribbon display to indicate the successful deployment.
The live link can be found here - https://code-institute-org.github.io/love-running-2.0/index.html
- The text for the Home page was taken from Wikipedia Article A
- Instructions on how to implement form validation on the Sign Up page was taken from Specific YouTube Tutorial
- The icons in the footer were taken from Font Awesome
- The photos used on the home and sign up page are from This Open Source site
- The images used for the gallery page were taken from this other open source site
Congratulations on completing your Readme, you have made another big stride in the direction of being a developer!
No errors have been found or reported.
- Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine. It allows you to run JavaScript code on the server side and is commonly used for building scalable network applications.
- CORS (Cross-Origin Resource Sharing) is a Node.js middleware that enables secure cross-origin communication in web applications. It allows you to define which domains are allowed to access your server resources.
- Express.js is a fast, unopinionated, and minimalist web framework for Node.js. It simplifies the process of building robust and scalable web applications and APIs.
- Mongoose is an Object Data Modeling (ODM) library for MongoDB and Node.js. It simplifies the interaction with MongoDB databases by providing a schema-based solution for data modeling.
- bcrypt is a library for hashing passwords securely in Node.js. It uses the bcrypt hashing algorithm to store and verify password hashes, making it a common choice for user authentication.
- dotenv is a zero-dependency module that loads environment variables from a .env file into the process.env object. It's commonly used to manage configuration settings in Node.js applications.
- express-async-errors is a middleware for Express.js that simplifies error handling in asynchronous routes. It allows you to throw errors in asynchronous code, and it will automatically handle them and send an appropriate response.
- jsonwebtoken JSON Web Tokens (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. In Node.js, the jsonwebtoken library is commonly used to create and verify JWTs for user authentication and authorization.
- mongoose-unique-validator is a plugin for Mongoose that provides additional validation for unique fields in MongoDB documents. It ensures that fields marked as unique are not duplicated in the database.
- morgan is middleware for Node.js that makes it easy to log HTTP requests in your application. It provides valuable information about incoming requests, such as HTTP methods, routes, status codes, and response times. This is especially useful for tracking and debugging requests in Express applications and other Node.js-based applications.
- cross-env is a command-line tool that allows you to set environment variables in a cross-platform way. It's often used in npm scripts to ensure consistent behavior across different operating systems.
- ESLint is a popular linting tool for JavaScript that helps developers find and fix problems in their code. It enforces coding standards and best practices to ensure code quality.
- Jest is a JavaScript testing framework that makes it easy to write unit and integration tests for your code. It provides a simple and powerful API for testing JavaScript applications.
- Nodemon is a utility that monitors for changes in your Node.js applications and automatically restarts the server when changes are detected. It's commonly used during development to streamline the development process.
- Supertest is a library for testing HTTP assertions in Node.js applications. It allows you to make HTTP requests and assert the responses to ensure that your API endpoints work as expected.
The version used in every library can be seen here in the package.json file.
- GitHub - Used to host and deploy the website as well as manage the project.
- Render - Used to deploy the website
- MongoDB - Used as database
This site was made using Visual Studio Code & GitHub. The site was further developed using NodeJS.
If you prefere Visual Studio Code (vscode):
code .In this project npm has been used as package manager, but you are free to use another package manager such as pnpm because of its popularity and speed.
npm install
npm startTo install mongoDB y the local computer. With windows the instruction are here and to mac I will use Homebrew:
brew tap mongodb/brew
brew install mongodb-communityFinally, type brew services start mongodb-community into your terminal. This is what actually starts up the Mongo server. You’ll need to have the Mongo server running any time you want to interact with your database, view your myFlix app, or use the Mongo shell.
To stop running the Mongo server, enter the command brew services stop mongodb-community in your terminal.
Below you will find a couple of extra tips that may be helpful when completing your project. Remember that each of these projects will become part of your final portfolio so it’s important to allow enough time to showcase your best work!
-
One of the most basic elements of keeping a healthy commit history is with the commit message. When getting started with your project, read through this article by Chris Beams on How to Write a Git Commit Message
- Make sure to keep the messages in the imperative mood
-
When naming the files in your project directory, make sure to consider meaningful naming of files, point to specific names and sections of content.
- For example, instead of naming an image used ‘image1.png’ consider naming it ‘landing_page_img.png’. This will ensure that there are clear file paths kept.
-
Do some extra research on good and bad coding practices, there are a handful of useful articles to read, consider reviewing the following list when getting started:
Getting started with your Portfolio Projects can be daunting, planning your project can make it a lot easier to tackle, take small steps to reach the final outcome and enjoy the process!
In this section you need to reference where you got your content, media and extra help from. It is common practice to use code from other repositories and tutorials, however, it is important to be very specific about these sources to avoid plagiarism.
You can break the credits section up into Content and Media, depending on what you have included in your project.
- https://www.makeareadme.com/#mind-reading
- https://ui.dev/amiresponsive
- https://github.com/goabstract/Awesome-Design-Tools/blob/master/README.md
- https://commonmark.org/help/tutorial/index.html
- https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
- https://stackoverflow.com/questions/26587527/cite-a-paper-using-github-markdown-syntax
- https://www.markdownguide.org/basic-syntax/
- Create ebook from markdown file with pandoc, examples and more details here
- Create table of contents: http://ecotrust-canada.github.io/markdown-toc/
- Colour palette from Coolors
- The sample images used are from: https://www.pexels.com/
- The logo was created by https://Logo.com
- Menu Icons and sections are from: https://fontawesome.com/
- The fonts used are from google font (Lora & Montserrat) as can be seen in the source code: https://fonts.google.com/
- To the html and css formater was using: https://codebeautify.org/