From d2a606f03cd45e1db03cf148f295d007110f0bcd Mon Sep 17 00:00:00 2001 From: Emil Gulamov <125820963+mearashadowfax@users.noreply.github.com> Date: Tue, 20 Feb 2024 20:50:32 +0400 Subject: [PATCH] Update code comments and enhance README documentation This commit improves the clarity of code comments in several Astro components for better understanding of their functionality. Changes were also made to the 'rounded' class in UI cards for improved visual appearance. In the README file, detailed explanations of project structure, customization process, key features, tools and technologies used, and their roles are provided to enhance project documentation. --- README.md | 315 +++++++++++++----- src/components/sections/FooterSection.astro | 12 +- .../sections/features/FeaturesGeneral.astro | 2 +- .../sections/features/FeaturesStatsAlt.astro | 1 + src/components/ui/cards/CardInsight.astro | 2 +- src/layouts/MainLayout.astro | 2 +- 6 files changed, 232 insertions(+), 102 deletions(-) diff --git a/README.md b/README.md index 1a19433..6d18f15 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,48 @@ # ScrewFast: Simplified Landing & Blog Template -![ScrewFast](https://github.com/mearashadowfax/ScrewFast/assets/125820963/5c6ef8aa-b859-49ce-9468-cf548c33c8fc) +![ScrewFast](https://github.com/mearashadowfax/ScrewFast/assets/125820963/5c6ef8aa-b859-49ce-9468-cf548c33c8fc.png) -ScrewFast is a landing and blog template crafted with simplicity and ease of use in mind. Designed for small to medium-sized projects, ScrewFast provides a seamless setup experience for developers and content creators alike. It combines the power of [Astro](https://astro.build/), [Tailwind CSS](https://tailwindcss.com/), and [Preline UI](https://preline.co/) to deliver a less complex, yet functional and visually appealing web presence. +ScrewFast is a landing and blog template crafted with simplicity and ease of use in mind. Designed for small to medium-sized projects, ScrewFast provides a seamless setup experience for developers and content creators alike. This template combines [Astro](https://astro.build/), [Tailwind CSS](https://tailwindcss.com/), and [Preline UI](https://preline.co/) for a functional and aesthetically pleasing web presence. ## Why Choose ScrewFast? -- **Simplified Architecture:** Whether you're building a portfolio, a company landing page, or a simple blog, ScrewFast's architecture is straightforward and easy to navigate, helping you get your project off the ground quickly. -- **Tailored for Smaller Projects:** With a focus on performance and minimal overhead, ScrewFast is ideal for projects that require a clean and professional online presence without the complexity of larger-scale solutions. -- **Customizable and Extensible:** While the core structure of the template prioritizes simplicity, it doesn't compromise on customizability. Tap into the potential of Astro's component-based architecture and Tailwind's utility-first styling to expand the template as needed. +- **Simplified Architecture**: Ideal for portfolios, company landing pages, or blogs, ScrewFast offers an easy-to-navigate structure that accelerates project deployment. +- **Tailored for Smaller Projects**: Prioritizing performance and minimal overhead, this template is perfect for a clean, professional online presence without the complexity. +- **Customizable and Extensible**: Offers the perfect balance between simplicity and customization using Astro's component model and Tailwind's utility styling. ## Features - **Astro Framework:** A web framework for building content-driven websites efficiently. - **Tailwind CSS:** A utility-first CSS framework for rapid UI development. -- **Preline UI:** A set of accessible and reusable components that are both attractive and functional. +- **Preline UI:** An open-source set of prebuilt UI components that enhance aesthetics and functionality. - **GSAP Integration:** Smooth, professional-grade animations to captivate your audience. -- **Markdown Content Collections:** Manage your product and blog content effortlessly with markdown. -- **SEO-Friendly:** Pages structured for optimal search engine performance. +- **Markdown Content Collections:** Easily organize and manage content using Markdown. +- **SEO-Friendly:** Structured for optimal search engine discoverability. - **Responsive Design:** Fully responsive layout to ensure your site looks great on all devices. ## Getting Started -This guide will help you set up the Astro project on your local machine and introduce you to some essential commands for development and deployment. +This guide will provide you with the necessary steps to set up and familiarize yourself with the Astro project on your local development machine. ### Installation -To begin, you'll need to install all the dependencies required for the project. Open your terminal, navigate to the project's root directory, and run the following command: +Start by installing the project dependencies. Open your terminal, navigate to the project's root directory, and execute: ```bash npm install ``` -This command will install all the dependencies listed in the project's `package.json` file. +This command will install all the necessary dependencies defined in the `package.json` file. ### Development Commands -After installing the dependencies, you can use these npm scripts for the development lifecycle of your project: +With dependencies installed, you can utilize the following npm scripts to manage your project's development lifecycle: -- `npm run dev`: Launches a local server with hot reloading. -- `npm run preview`: Previews the build locally. -- `npm run astro`: Executes Astro CLI commands. -- `npm run astro --help`: Provides help information for Astro commands. +- `npm run dev`: Starts a local development server with hot reloading enabled. +- `npm run preview`: Serves your build output locally for preview before deployment. +- `npm run build`: Bundles your site into static files for production. -Learn more about Astro's CLI by referring to [Astro's documentation](https://docs.astro.build/). +For detailed help with Astro CLI commands, visit [Astro's documentation](https://docs.astro.build/en/reference/cli-reference/). ## Deployment @@ -62,42 +61,42 @@ This creates a `dist/` directory with your built site (configurable via [outDir To deploy ScrewFast to Vercel, follow these steps: 1. Clone this repository to your GitHub account. -2. Click the button below to start deploying your forked copy on Vercel: +2. Click the button below to start deploying your project on Vercel: ## Project Structure
-ScrewFast is organized into modular components, content, and layout systems, making development and content management a breeze. Here's a quick overview of the project's directory structure: +ScrewFast organizes modular components, content, and layouts to streamline development and content management. Expand for a detailed overview of the directory structure: -
+
```md src/ ├── components/ # Reusable components │ ├── Meta.astro # Meta component for SEO -│ ├── sections/ # Sectional components for various parts of the website -│ ├── ThemeIcon.astro # Theme switcher icon component -│ └── ui/ # UI components categorized by their functionality -├── content/ # Content files in markdown for blog posts, insights, and products -│ ├── blog/ # Blog posts written in markdown -│ ├── insights/ # Insights articles -│ ├── products/ # Product details -│ └── config.ts # Site configuration -├── images/ # Image assets for the website -├── layouts/ # Layout components -│ └── MainLayout.astro # Main layout component -├── pages/ # Astro pages representing each website section or view +│ ├── sections/ # Components for various sections of the website +│ ├── ThemeIcon.astro # Component for toggling light/dark themes +│ └── ui/ # UI components categorized by functionality +├── content/ # Markdown files for blog posts, insights, products, and site configuration +│ ├── blog/ +│ ├── insights/ +│ ├── products/ +│ └── config.ts # Contains site-wide configuration options +├── images/ # Static image assets for use across the website +├── layouts/ # Components defining layout templates +│ └── MainLayout.astro # The main wrapping layout for all pages +├── pages/ # Astro files representing individual pages and website sections │ ├── 404.astro # Custom 404 page -│ ├── blog/ # Blog listing and post pages -│ ├── contact.astro # Contact page -│ ├── index.astro # Home page -│ ├── insights/ # Insights listing and detail pages -│ ├── products/ # Product listing and detail pages -│ ├── robots.txt.ts # Dynamic generation of robots.txt -│ └── services.astro # Services offered -└── utils/ # Utility functions +│ ├── blog/ +│ ├── contact.astro +│ ├── index.astro # The landing/home page +│ ├── insights/ +│ ├── products/ +│ ├── robots.txt.ts # Dynamically generates robots.txt +│ └── services.astro +└── utils/ # Shared utility functions and helpers ``` @@ -107,18 +106,9 @@ src/
-The `public` directory contains all the static files that your project can serve directly to the browser. Here's a breakdown of the contents within the `public` folder: +Static files served directly to the browser are within the `public` directory at the root of the project. Expand for the layout: -
-- Favicons and device icons (e.g., `favicon.ico`, `apple-touch-icon.png`) -- PWA (Progressive Web App) manifest and icons for improved mobile support (e.g., `manifest.webmanifest`, `icon-512.png`) -- `social.png`: An image for social media sharing previews -- `scripts`: Third-party libraries and scripts - - `gsap`: GreenSock Animation Platform files for creating high-performance animations - - `lenis`: Smooth scrolling library for improved scroll interactions - - `preline`: Set of UI component scripts from Preline UI - -Here's the layout of the `public` directory: +
```md @@ -133,31 +123,145 @@ public/ ├── maskable_icon_x512.png ├── scripts/ │ └── vendor/ -│ ├── gsap/ -│ │ └── gsap.min.js -│ ├── lenis/ +│ ├── gsap/ # Animations powered by GSAP (GreenSock Animation Platform) +│ │ └── gsap.min.js +│ ├── lenis/ # Lenis script for smooth scrolling effects │ │ └── lenis.js -│ └── preline/ +│ └── preline/ # Preline UI plugins │ ├── accordion/ │ ├── collapse/ │ ├── overlay/ │ └── tabs/ -└── social.png +└── social.png # Image used for social media sharing previews ``` -When adding or updating icons and favicons, ensure that they match the sizes expected by various devices and that they're referenced correctly in the head of your HTML document. - The scripts in the `public/scripts/vendor` directory are essential for the interactivity and aesthetic features of the website. Do not remove these unless you plan to replace their functionality.
+## Customization + +
+ +ScrewFast allows for easy customization to suit your specific needs. Here are a couple of ways you can configure components and content: + + +### Editing Component Variables + +Some components have properties defined as TypeScript variables within the component file. Here's an example of customizing the `FeaturesGeneral` component: + +```typescript +// Define the string variables title and subTitle for the main heading and sub-heading text. +const title: string = "Meeting Industry Demands"; +const subTitle: string = + "At ScrewFast, we tackle the unique challenges encountered in the hardware and construction sectors. From cutting-edge tools to expert services, we're dedicated to helping you overcome obstacles and achieve your goals."; +``` + +For collections of content like testimonials or statistics, edit the corresponding array of objects: + +```typescript +// An array of testimonials +const testimonials: Testimonial[] = [...]; + +// An array of statistics +const statistics: StatProps[] = [...]; +``` + +Modify the content within these arrays to reflect your data. + +### Props in Component Instances + +You can pass values to props directly in the page files for components used across pages. Here's an example of a `HeroSection` and `ClientsSection` component with inline props: + +```html + + + +``` + +Edit the props such as `title`, `subTitle`, `primaryBtn`, etc., to personalize these sections. Ensure that you maintain the structure and data types of the props. + +### Customizing Navigation and Footer Links + +Edit the `navigation.ts` file within the `utils` directory to manage navigation bar and footer links: + +#### Navigation Bar Links + +Edit the `navBarLinks` array to adjust navigation bar links: + +```typescript +// An array of links for the navigation bar +export const navBarLinks: NavLink[] = [ + { name: "Home", url: "/" }, + { name: "Products", url: "/products" }, + { name: "Services", url: "/services" }, + { name: "Blog", url: "/blog" }, + { name: "Contact", url: "/contact" }, +]; +``` + +Replace `name` with the display text and `url` with the appropriate path to pages on your site. + +#### Footer Links + +Similarly, adjust the links displayed in the footer by editing the `footerLinks` array: + +```typescript +// An array of links for the footer +export const footerLinks: FooterLinkSection[] = [ + { + section: "Product", + links: [ + { name: "Tools & Equipment", url: "/tools-equipment" }, + { name: "Construction Services", url: "/construction-services" }, + { name: "Pricing", url: "/pricing" }, + ], + }, + { + section: "Company", + links: [ + { name: "About us", url: "/about" }, + { name: "Blog", url: "/blog" }, + { name: "Careers", url: "/careers" }, + { name: "Customers", url: "/customers" }, + ], + }, +]; +``` + +Each section within the `footerLinks` array represents a group of links. Update the `section` value for the group heading and modify each link's `name` and `url` as needed. + +#### Social Media Links + +Replace the placeholder URLs in the `socialLinks` object with your social media profiles: + +```typescript +// An object of links for social icons +export const socialLinks: SocialLinks = { + facebook: "#", + twitter: "#", + github: "#", + linkedin: "#", + instagram: "#", +}; +``` + +Remember to add complete and valid URLs for the navigation to function properly. These customizations will reflect throughout your Astro site, promoting consistency across all pages. +
+ ## Integrations and Enhancements
-ScrewFast leverages the power of Astro and associated integrations to deliver exceptional site performance and a seamless user experience. Here are some notable integrations and enhancements included in the project: +ScrewFast leverages the power of Astro — a modern, cutting-edge site building framework — and integrates it seamlessly with the utility-first CSS framework TailwindCSS, to deliver exceptional site performance and a seamless user experience. Here are some notable integrations and enhancements included in the project: -
### Lenis for Smooth Scrolling @@ -165,7 +269,7 @@ Experience buttery smooth scrolling with [Lenis](https://lenis.studiofreight.com Here's how we set up Lenis in `src/layouts/MainLayout.astro`: -```html +```astro