From: Arnaud Guéras Date: Thu, 12 Dec 2024 07:35:55 +0000 (+0100) Subject: add more docs X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=0047f0051721497078e81eadedc72e13ace62c41;p=www-xenproject-org.git add more docs Signed-off-by: Arnaud Guéras --- diff --git a/docs/components.md b/docs/components.md new file mode 100644 index 0000000..005402f --- /dev/null +++ b/docs/components.md @@ -0,0 +1,49 @@ +--- +title: "Components" +description: "Advanced editing features, particularly the use of reusable components" +--- + +# Components + +This page describes the use of reusable components. + +There are predefined components that you can insert into your pages. They help maintain visual and functional consistency throughout the site. + +Here are the main components you can use: + +Click on the component image to see the full documentation. + +### [Section](components/section.md) + +Section are used to create distinct content sections with customizable styles and layouts. +They are mandatory for every components or content blocks. + +[Section component](components/section.md) + + +### [Media-block](components/media-block.md) + +[![Media block component](images/media-block--left-thumb.png)](components/media-block.md) +[Media block component](components/media-block.md) + +### [Features List](components/feature-lists.md) + +[![Features list component](images/features-list-thumb.png)](components/feature-lists.md) +[Features list component](components/feature-lists.md) + +### [Carousel](components/carousel.md) + +[![Carousel component](images/carousel-thumb.png)](components/carousel.md) +[Carousel component](components/carousel.md) + +### [Latest News](components/latest-news.md) + +[![Latest news component](images/latest-news-thumb.png)](components/latest-news.md) +[Latest news component](components/latest-news.md) + + +### [Vertical Lists](components/vertical-lists.md) + +[![Vertical lists component](images/vertical-lists-thumb.png)](components/vertical-lists.md) +[Vertical lists component](components/vertical-lists.md) + diff --git a/docs/components/carousel.md b/docs/components/carousel.md index 87a86e1..f1fdd8c 100644 --- a/docs/components/carousel.md +++ b/docs/components/carousel.md @@ -5,15 +5,23 @@ description: "A carousel component for displaying a rotating list of items" # Carousel Component -[![Carousel component](../images/carousel-thumb.png)](../images/carousel.png) The carousel component allows you to display a rotating list of items in a slider format with navigation buttons. +[![Carousel component](../images/carousel-thumb.png)](../images/carousel.png) + + +- [Basic Usage](#basic-usage) +- [With Custom Class](#with-custom-class) +- [Structure of Project Items](#structure-of-project-items) +- [HTML Structure](#html-structure) +- [Features](#features) + ## Basic Usage The most common use case is to display all projects using the `getpages` shortcode: -```html +```markdown {{}} {{}} {{}} @@ -23,7 +31,7 @@ The most common use case is to display all projects using the `getpages` shortco You can add a custom class to the carousel container: -```html +```markdown {{}} {{}} {{}} diff --git a/docs/components/feature-lists.md b/docs/components/feature-lists.md index 7f9c145..0e43644 100644 --- a/docs/components/feature-lists.md +++ b/docs/components/feature-lists.md @@ -4,6 +4,14 @@ The `features-list` component allows you to display a grid of features with icons, titles, and descriptions. +- [Usage](#usage) +- [Parameters](#parameters) + - [Shortcode Parameters](#shortcode-parameters) + - [Item Parameters](#item-parameters) +- [Example](#example) +- [Technical Notes](#technical-notes) + + ## Usage To use this component in your Markdown pages, use the following shortcode syntax: diff --git a/docs/components/full-width-image.md b/docs/components/full-width-image.md new file mode 100644 index 0000000..d7c77ed --- /dev/null +++ b/docs/components/full-width-image.md @@ -0,0 +1,87 @@ +--- +title: "Full Width Image Component" +description: "Documentation for the full-width-image shortcode" +date: 2023-12-11 +draft: false +--- + +# Full Width Image Component + +The full-width-image component is used to display images that span the full width of their container, with various styling options. + +## Usage + +Basic usage: + +```markdown +{{}} +``` + +## Parameters + +| Parameter | Description | Required | Default | +| --------- | ----------------------- | -------- | ------------------ | +| src | Image source URL | Yes | - | +| alt | Alternative text | Yes | "Full width image" | +| title | Image title | No | - | +| class | Additional CSS classes | No | - | +| imgClass | Classes for img element | No | - | + +## Examples + +### Basic Full Width Image + +```markdown +{{}} +``` + +### Rounded Corners Image + +```markdown +{{}} +``` + +### Image with Custom Classes + +```markdown +{{}} +``` + +## Available Classes + +### Container Classes +- `rounded-corners`: Adds rounded corners to the image container +- `shadow-sm`: Adds small shadow +- `shadow-lg`: Adds large shadow +- `mg-t-sm`: Adds small top margin +- `mg-b-sm`: Adds small bottom margin + +### Image Classes +- `opacity-90`: Sets image opacity to 90% +- `grayscale`: Converts image to grayscale +- `blur-sm`: Adds slight blur effect + +## Best Practices + +1. Always provide descriptive alt text for accessibility +2. Optimize images before uploading (compress, proper dimensions) +3. Use appropriate image formats (JPEG for photos, PNG for graphics) +4. Consider loading time when using large images +5. Test how images appear on different screen sizes \ No newline at end of file diff --git a/docs/components/latest-news.md b/docs/components/latest-news.md index 49190f5..ffa4295 100644 --- a/docs/components/latest-news.md +++ b/docs/components/latest-news.md @@ -5,9 +5,14 @@ description: "A component for displaying the latest blog posts in a carousel" # Latest News Component +The Latest News component displays the most recent blog posts in a carousel format with navigation buttons. It automatically fetches and displays up to 10 latest posts from the blog section. + [![Latest news component](../images/latest-news-thumb.png)](../images/latest-news.png) -The Latest News component displays the most recent blog posts in a carousel format with navigation buttons. It automatically fetches and displays up to 10 latest posts from the blog section. +- [Basic Usage](#basic-usage) +- [Features](#features) + + ## Basic Usage diff --git a/docs/components/media-block.md b/docs/components/media-block.md index 83d7bbc..6f84bd3 100644 --- a/docs/components/media-block.md +++ b/docs/components/media-block.md @@ -1,55 +1,87 @@ -# media-block +--- +title: "Media Block Component" +description: "Documentation for the media-block shortcode" +date: 2023-12-11 +draft: false +--- + +# Media Block Component + +The media block component is used to create sections that combine media (images or videos) with text content. It's highly flexible and can be used for various layouts. + [![Media block with left media position](../images/media-block--left-thumb.png)](../images/media-block--left.png) [![Media block with right media position](../images/media-block--right-thumb.png)](../images/media-block--right.png) +- [Usage](#usage) +- [Parameters](#parameters) +- [Examples](#examples) + - [Image with Right-aligned Media](#image-with-right-aligned-media) + - [Video Integration](#video-integration) +- [Best Practices](#best-practices) + + + +## Usage + +Basic usage: + +```markdown +{{}} +Your content goes here +{{}} +``` + +## Parameters + +| Parameter | Description | Required | Default | +| ------------- | ------------------------------------- | -------- | ------- | +| title | Block title | No | "" | +| media | URL to media (image or video) | Yes | - | +| alt | Alt text for media | Yes | - | +| mediaPosition | Position of media ("left" or "right") | No | "left" | +| animate | Enable animation | No | false | +| titleLevel | Heading level (1-6) | No | 2 | +| titleClass | Additional CSS classes for title | No | "" | +| class | Additional CSS classes for block | No | "" | + +## Examples + +### Image with Right-aligned Media -The `media-block` is a flexible component for displaying content with a media element (image, video, or other component). ```markdown -{{}} -{{}} - ## A remarkable innovation - - Our revolutionary new technology improves productivity by **50%**. - Discover its main features: - - * Optimized performance - * Intuitive interface - * Maximum compatibility -{{}} -
- - Request a demo - -
-{{}} +*/>}} +This feature provides powerful capabilities for... +{{}} ``` -| Parameter | Type | Default | Description | -| --------------------- | ------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `title` | string | - | Block title. Supports markdown for bold (`**text**`) and italic (`*text*`) | -| `media` | string | - | URL of image/video or shortcode of another component. Supports: images (png, jpg, jpeg, avif, webp, gif, svg), videos (mp4), YouTube, SlideShare and partial or HTML components | -| `mediaPosition` | string | "left" | Position of media element: `"left"` or `"right"` | -| `mobileMediaPosition` | string | "left" | Position of media element on mobile: `"top"` or `"bottom"` | -| `imageAlt` | string | "Media image" | Alternative text for image | -| `imageSize` | string | - | Image size (width in pixels) | -| `label` | string | - | Optional label above title | -| `titleLevel` | string | "2" | HTML title level (h1-h6) | -| `titleClass` | string | - | Additional CSS classes for title | -| `class` | string | - | Additional CSS classes for block | -| `animate` | string | "false" | Activates block animation: `"true"` or `"false"` | - -The content between the shortcode tags can include Markdown and HTML. - -TODO: ajoute un paragraphe qui explique l'utilisation du tag md dans la partie texte du meidablock \ No newline at end of file +### Video Integration + +```markdown +{{}} +Watch this tutorial to learn how to... +{{}} +``` + +## Best Practices + +1. Always provide descriptive alt text +2. Use animation sparingly +3. Keep content concise and focused +4. Test different media positions for optimal layout +5. Ensure media files are optimized for web use \ No newline at end of file diff --git a/docs/components/section.md b/docs/components/section.md new file mode 100644 index 0000000..54af0ce --- /dev/null +++ b/docs/components/section.md @@ -0,0 +1,93 @@ +--- +title: "Section Component" +description: "Documentation for the section shortcode" +date: 2023-12-11 +draft: false +--- + +# Section Component + +The section component is used to create distinct content sections with customizable styles and layouts. + +- [Usage](#usage) +- [Available Classes](#available-classes) + - [Layout Classes](#layout-classes) + - [Style Classes](#style-classes) +- [Examples](#examples) + - [Centered Content Section](#centered-content-section) + - [Feature Section](#feature-section) +- [Best Practices](#best-practices) + + +## Usage + +Basic usage: + +```markdown +{{}} +Your content here +{{}} +``` + +With classes: + +```markdown +{{}} +Your centered content here +{{}} +``` + +## Available Classes + +### Layout Classes +- `txt-c`: Center-align text +- `txt-l`: Left-align text +- `txt-r`: Right-align text + +### Style Classes +- `section-square-primary`: Primary colored background with square corners +- `section-rounded`: Rounded corners +- `section-dark`: Dark background +- `section-light`: Light background + +## Examples + +### Centered Content Section + +```markdown +{{}} +{{}} +## Join the **Community** + +Connect with other developers and share your experience. +{{}} + +

+ + Join Now + +

+{{}} +``` + +### Feature Section + +```markdown +{{}} +{{}} +## Key Features + +- Fast and efficient +- Easy to use +- Highly customizable +{{}} +{{}} +``` + +## Best Practices + +1. Use consistent styling across similar sections +2. Combine with other components like `md` for rich content +3. Keep sections focused on a single topic or purpose +4. Use appropriate spacing between sections +5. Choose colors and styles that match your site's theme \ No newline at end of file diff --git a/docs/components/vertical-lists.md b/docs/components/vertical-lists.md index 99e2b86..e76a29f 100644 --- a/docs/components/vertical-lists.md +++ b/docs/components/vertical-lists.md @@ -9,6 +9,15 @@ description: "Documentation for the vertical-lists component" The `vertical-lists` component allows you to create columnar layouts with titled sections. Each section can contain text, links, or other content. +- [Usage](#usage) +- [Parameters](#parameters) +- [List Item Properties](#list-item-properties) +- [Examples](#examples) + - [Example with Mixed Title Formatting](#example-with-mixed-title-formatting) +- [Styling](#styling) +- [Best Practices](#best-practices) + + ## Usage Basic structure: diff --git a/docs/hugo-tutorial.md b/docs/hugo-tutorial.md new file mode 100644 index 0000000..50b8f2a --- /dev/null +++ b/docs/hugo-tutorial.md @@ -0,0 +1,190 @@ +--- +title: "Hugo Website Tutorial" +description: "A comprehensive guide for managing and editing the Xen Project website" +date: 2023-12-11 +draft: false +--- + +# Hugo Website Tutorial + +This tutorial will guide you through the common tasks for managing and updating the Xen Project website. We'll cover everything from basic content updates to advanced component usage. + +## Table of Contents + +- [Table of Contents](#table-of-contents) +- [Basic Content Management](#basic-content-management) + - [Headers and Content](#headers-and-content) + - [Page Structure](#page-structure) +- [Working with Images](#working-with-images) + - [Adding Images](#adding-images) + - [Image Sizing](#image-sizing) +- [Page Components](#page-components) + - [Downloadable Content](#downloadable-content) +- [Site Navigation](#site-navigation) + - [Adding New Pages](#adding-new-pages) + - [Header/Footer Modification](#headerfooter-modification) +- [Best Practices](#best-practices) +- [Component Reference](#component-reference) + +## Basic Content Management + +### Headers and Content + +Each page in the website starts with a YAML frontmatter section that defines its metadata: + +```yaml +--- +title: "Your Page Title" +description: "Page description for SEO" +keywords: "keyword1, keyword2" +date: 2024-01-14T07:07:07+01:00 +draft: false +menus: + main: + parent: Resources + weight: 12 +--- +``` + +### Page Structure + +Pages are structured using sections and components. Here's a basic example: + +```markdown +{{}} +{{}} +Your content goes here +{{}} +{{}} +``` + +## Working with Images + +### Adding Images + +Images can be added using several methods: + +1. Placement + +All images should be placed in the `static/img` folder. + +Be mindful of image file sizes - they should be less than 150kb. It's recommended to convert images to the `webp` format. + +You can use the [Squoosh](https://squoosh.app/) tool to convert your images to webp format. + +You can view most of the images used on the website in the [Images Reference](images.md) page. + + +2. Full-width images: +```markdown +{{}} +``` + +3. Regular images in content markdown: +```markdown +![Alt text](/img/your-image.png) +``` + +4. Regular images in content HTML : +```html +Image description +``` + +5. Full-width images in content markdown: + +While less commonly used, this method is available when needed. + +```markdown +{{}} +``` + +### Image Sizing + +Control image sizes using classes or direct HTML attributes: + +```markdown +{{}} +``` + +Available image classes: +- `small-image`: 300px max width +- `medium-image`: 500px max width +- `large-image`: 800px max width +- `rounded-corners`: Adds rounded corners + +## Page Components + +All page components are available in the [Components Guide](components.md) + + +### Downloadable Content + +Add downloadable resources: + +```markdown +{{}} +``` + +## Site Navigation + +### Adding New Pages + +1. Create a new `.md` file in the appropriate content directory +2. Include proper frontmatter +3. Add to menu structure if needed: + +```yaml +menus: + main: + parent: Parent Section + weight: 10 +``` + +### Header/Footer Modification + +Header and footer content can be modified in the theme configuration: + +1. Navigate to `themes/xen-project/layouts/partials/` +2. Edit `header.html` or `footer.html` + +## Best Practices + +1. Always include descriptive alt text for images +2. Use semantic heading structure (h1 > h2 > h3) +3. Keep URLs and file paths lowercase and hyphen-separated +4. Optimize images before uploading +5. Test pages in both desktop and mobile views + +## Component Reference + +Common shortcodes available: + +- `section`: Create content sections +- `media-block`: Text with media combinations +- `full-width-image`: Full-width responsive images +- `md`: Markdown content within other components +- `get-downloads-links`: Resource downloads section + +For detailed component documentation, see the [Components Guide](components/) \ No newline at end of file diff --git a/docs/page-components.md b/docs/page-components.md deleted file mode 100644 index e73680b..0000000 --- a/docs/page-components.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Components" -description: "Advanced editing features, particularly the use of reusable components" ---- - -# Components - -This page describes the use of reusable components. - -There are predefined components that you can insert into your pages. They help maintain visual and functional consistency throughout the site. - -Here are the main components you can use: - -Click on the component image to see the full documentation. - -### Media-block - -[![Media block component](images/media-block--left-thumb.png)](components/media-block.md) - - -### Features List - -[![Features list component](images/features-list-thumb.png)](components/feature-lists.md) - - -### Carousel - -[![Carousel component](images/carousel-thumb.png)](components/carousel.md) - - -### Latest News - -[![Latest news component](images/latest-news-thumb.png)](components/latest-news.md) - - -### Vertical Lists - -[![Vertical lists component](images/vertical-lists-thumb.png)](components/vertical-lists.md) - - diff --git a/themes/xen-project/assets/css/utils.scss b/themes/xen-project/assets/css/utils.scss index bfed75a..2892dca 100644 --- a/themes/xen-project/assets/css/utils.scss +++ b/themes/xen-project/assets/css/utils.scss @@ -10,6 +10,23 @@ img.rounded-corners, .rounded-corners img { border-radius: 16px; } +.small-image, +.medium-image, +.large-image { + max-width: 100%; +} + +.small-image { + max-width: 300px; +} + +.medium-image { + max-width: 500px; +} + +.large-image { + max-width: 800px; +} .w-100 { width: 100%;