@mgks/docmd 0.3.2 → 0.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +5 -1
  2. package/package.json +28 -24
  3. package/.gitattributes +0 -2
  4. package/.github/CODE_OF_CONDUCT.md +0 -48
  5. package/.github/CONTRIBUTING.md +0 -129
  6. package/.github/FUNDING.yml +0 -15
  7. package/.github/ISSUE_TEMPLATE/bug_report.yml +0 -58
  8. package/.github/ISSUE_TEMPLATE/feature_request.yml +0 -27
  9. package/.github/PULL_REQUEST_TEMPLATE.md +0 -16
  10. package/.github/SECURITY.md +0 -18
  11. package/.github/workflows/deploy-docmd.yml +0 -45
  12. package/.github/workflows/npm-publish.yml +0 -49
  13. package/assets/css/welcome.css +0 -6
  14. package/assets/images/preview-dark-1.webp +0 -0
  15. package/assets/images/preview-dark-2.webp +0 -0
  16. package/assets/images/preview-dark-3.webp +0 -0
  17. package/assets/images/preview-dark-welcome.png +0 -0
  18. package/assets/images/preview-light-1.webp +0 -0
  19. package/assets/images/preview-light-2.webp +0 -0
  20. package/assets/images/preview-light-3.webp +0 -0
  21. package/docs/cli-commands.md +0 -108
  22. package/docs/comparison.md +0 -56
  23. package/docs/configuration.md +0 -289
  24. package/docs/content/containers/buttons.md +0 -88
  25. package/docs/content/containers/callouts.md +0 -154
  26. package/docs/content/containers/cards.md +0 -93
  27. package/docs/content/containers/changelogs.md +0 -128
  28. package/docs/content/containers/collapsible.md +0 -89
  29. package/docs/content/containers/index.md +0 -35
  30. package/docs/content/containers/nested-containers.md +0 -329
  31. package/docs/content/containers/steps.md +0 -175
  32. package/docs/content/containers/tabs.md +0 -228
  33. package/docs/content/custom-containers.md +0 -24
  34. package/docs/content/frontmatter.md +0 -84
  35. package/docs/content/images.md +0 -205
  36. package/docs/content/index.md +0 -19
  37. package/docs/content/markdown-syntax.md +0 -309
  38. package/docs/content/mermaid.md +0 -723
  39. package/docs/content/no-style-example.md +0 -112
  40. package/docs/content/no-style-pages.md +0 -226
  41. package/docs/content/search.md +0 -68
  42. package/docs/contributing.md +0 -101
  43. package/docs/deployment.md +0 -120
  44. package/docs/getting-started/basic-usage.md +0 -89
  45. package/docs/getting-started/index.md +0 -21
  46. package/docs/getting-started/installation.md +0 -75
  47. package/docs/index.md +0 -168
  48. package/docs/overview.md +0 -63
  49. package/docs/plugins/analytics.md +0 -75
  50. package/docs/plugins/index.md +0 -70
  51. package/docs/plugins/seo.md +0 -127
  52. package/docs/plugins/sitemap.md +0 -87
  53. package/docs/recipes/custom-fonts.md +0 -43
  54. package/docs/recipes/favicon.md +0 -38
  55. package/docs/recipes/index.md +0 -12
  56. package/docs/recipes/landing-page.md +0 -46
  57. package/docs/theming/assets-management.md +0 -126
  58. package/docs/theming/available-themes.md +0 -77
  59. package/docs/theming/custom-css-js.md +0 -79
  60. package/docs/theming/icons.md +0 -92
  61. package/docs/theming/index.md +0 -19
  62. package/docs/theming/light-dark-mode.md +0 -114
  63. package/src/assets/images/docmd-preview.png +0 -0
package/docs/plugins/seo.md DELETED
@@ -1,127 +0,0 @@
1
- ---
2
- title: "SEO & Meta Tags Plugin"
3
- description: "Configure Search Engine Optimization (SEO) meta tags to improve your docmd site's discoverability."
4
- ---
5
-
6
- # SEO & Meta Tags Plugin (`seo`)
7
-
8
- The `seo` plugin automatically generates important meta tags in the `<head>` of your HTML pages. This helps search engines and social media platforms understand, index, and display your content more effectively.
9
-
10
- ## Enabling the Plugin
11
-
12
- Add the `seo` plugin to the `plugins` object in your config file:
13
-
14
- ```javascript
15
- module.exports = {
16
- // ...
17
- plugins: {
18
- seo: {
19
- defaultDescription: 'Discover insightful articles and guides on Project X. Your go-to resource for learning and development.',
20
- openGraph: {
21
- // siteName: 'Project X Documentation', // Optional, defaults to config.siteTitle
22
- defaultImage: '/assets/images/default-og-image.png', // Absolute path from site root
23
- },
24
- twitter: {
25
- cardType: 'summary_large_image', // e.g., 'summary', 'summary_large_image'
26
- // siteUsername: '@ProjectX_Docs', // Your site's Twitter handle
27
- // creatorUsername: '@YourHandle' // Default author handle (override in frontmatter)
28
- }
29
- },
30
- // ... other plugins
31
- },
32
- // ...
33
- };
34
- ```
35
-
36
- ## Configuration Options
37
-
38
- The options in the config file serve as site-wide defaults. For the best results, you should provide specific metadata for each page using frontmatter.
39
-
40
- ## Frontmatter for SEO
41
-
42
- To control SEO on a per-page basis, add a nested `seo` object to your page's frontmatter. This keeps all SEO-related settings organized and prevents conflicts with other frontmatter keys.
43
-
44
- ```yaml
45
- ---
46
- title: "Advanced Widget Configuration"
47
- description: "A detailed guide on configuring advanced settings for the Super Widget."
48
- seo:
49
- description: "A more specific SEO description for search engines, overriding the main description if needed."
50
- image: "/assets/images/widgets/super-widget-social.jpg"
51
- ogType: "article"
52
- twitterCard: "summary_large_image"
53
- twitterCreator: "@widgetMaster"
54
- keywords: ["widget", "configuration", "advanced", "performance"]
55
- permalink: "https://example.com/docs/widgets/advanced-configuration"
56
- noindex: false
57
- ---
58
- ```
59
-
60
- ::: callout info Backward Compatibility
61
- For backward compatibility, the plugin will still recognize top-level SEO fields like `image`, `ogType`, etc. However, the nested `seo:` structure is the recommended approach.
62
- :::
63
-
64
- ### Supported Frontmatter Fields
65
-
66
- All fields should be placed inside the `seo:` object.
67
-
68
- * `description` (String): Overrides the main page description for SEO meta tags.
69
- * `image` or `ogImage` (String): Path to an image for `og:image` and `twitter:image`.
70
- * `ogType` (String): Overrides the default Open Graph type (e.g., `article`, `website`).
71
- * `twitterCard` (String): Overrides the default Twitter card type for this page.
72
- * `twitterCreator` (String): The Twitter @username of the page's author.
73
- * `keywords` (Array of Strings or String): Keywords for the `<meta name="keywords">` tag.
74
- * `permalink` or `canonicalUrl` (String): The canonical URL for the page.
75
- * `noindex` (Boolean): If `true`, adds `<meta name="robots" content="noindex">` to discourage search engines from indexing this page.
76
-
77
- ## Structured Data (LD+JSON)
78
-
79
- The SEO plugin can generate [Structured Data](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data) (LD+JSON), which can enable rich search results. This feature is enabled per-page in your frontmatter.
80
-
81
- ### Enabling Structured Data
82
-
83
- To generate a default LD+JSON block, add `ldJson: true` inside your `seo` frontmatter object.
84
-
85
- ```yaml
86
- ---
87
- title: "My Article"
88
- description: "An article about something important."
89
- seo:
90
- ldJson: true
91
- ---
92
- ```
93
-
94
- This generates a basic `Article` schema using your page's metadata.
95
-
96
- ### Customizing Structured Data
97
-
98
- For more control, provide an object to `ldJson`. This object will be merged with the default data, allowing you to add or override any properties.
99
-
100
- **Example: Customizing schema type and adding an author**
101
-
102
- ```yaml
103
- ---
104
- title: "Advanced Widget Configuration"
105
- description: "A detailed guide on configuring advanced settings for the Super Widget."
106
- seo:
107
- image: "/assets/images/widgets/super-widget-social.jpg"
108
- ldJson:
109
- "@type": "TechArticle"
110
- author:
111
- "@type": "Person"
112
- name: "Jane Doe"
113
- url: "https://example.com/authors/jane-doe"
114
- datePublished: "2024-01-15"
115
- review:
116
- "@type": "Review"
117
- reviewRating:
118
- "@type": "Rating"
119
- ratingValue: "5"
120
- bestRating: "5"
121
- author:
122
- "@type": "Person"
123
- name: "John Smith"
124
- ---
125
- ```
126
-
127
- In this example, the schema type is changed to `TechArticle`, and detailed `author`, `datePublished`, and `review` information is added, giving search engines a much richer understanding of your content.
package/docs/plugins/sitemap.md DELETED
@@ -1,87 +0,0 @@
1
- ---
2
- title: "Sitemap Plugin"
3
- description: "Automatically generate a sitemap.xml for your docmd site to improve search engine discoverability."
4
- ---
5
-
6
- # Sitemap Plugin (`sitemap`)
7
-
8
- The `sitemap` plugin automatically generates a `sitemap.xml` file for your documentation site. This helps search engines discover, crawl, and index your content more effectively, which can improve your site's visibility in search results.
9
-
10
- ## Enabling the Plugin
11
-
12
- Add the `sitemap` plugin to the `plugins` object in your config file:
13
-
14
- ```javascript
15
- module.exports = {
16
- // ...
17
- plugins: {
18
- sitemap: {
19
- defaultChangefreq: 'weekly',
20
- defaultPriority: 0.8
21
- },
22
- // ... other plugins
23
- },
24
- // ...
25
- };
26
- ```
27
-
28
- ## Configuration Options
29
-
30
- All options for the `sitemap` plugin are optional. If an option is not provided, the plugin will use sensible defaults.
31
-
32
- * `defaultChangefreq` (String):
33
- * Specifies how frequently the content is likely to change
34
- * Possible values: `'always'`, `'hourly'`, `'daily'`, `'weekly'`, `'monthly'`, `'yearly'`, `'never'`
35
- * Default: `'weekly'`
36
-
37
- * `defaultPriority` (Number):
38
- * Indicates the relative importance of a page in your site
39
- * Value between 0.0 and 1.0
40
- * Default: `0.8`
41
-
42
- ## How It Works
43
-
44
- The sitemap plugin automatically:
45
-
46
- 1. Scans all generated HTML pages during the build process
47
- 2. Creates a `sitemap.xml` file in the root of your site output directory
48
- 3. Includes all pages with their URLs, last modification dates, and configured priorities
49
-
50
- The plugin uses your `siteUrl` property from the config file to create absolute URLs, which is required for a valid sitemap. Make sure you have a `siteUrl` defined:
51
-
52
- ```javascript
53
- module.exports = {
54
- siteUrl: 'https://yourdomain.com', // No trailing slash
55
- // ... other config
56
- };
57
- ```
58
-
59
- ## Overriding Per-Page Settings with Frontmatter
60
-
61
- You can override the default sitemap settings for individual pages by adding specific frontmatter properties:
62
-
63
- ```yaml
64
- ---
65
- title: "Important Page"
66
- description: "This is a very important page that changes frequently"
67
- sitemap:
68
- changefreq: 'daily'
69
- priority: 1.0
70
- ---
71
- ```
72
-
73
- ## Excluding Pages from the Sitemap
74
-
75
- If you want to exclude specific pages from the sitemap, you can add the following to your frontmatter:
76
-
77
- ```yaml
78
- ---
79
- title: "Private Page"
80
- description: "This page should not appear in search engines"
81
- sitemap: false
82
- ---
83
- ```
84
-
85
- ## Verifying Your Sitemap
86
-
87
- After building your site, check the generated sitemap at `your-site/sitemap.xml`. You can also submit the sitemap URL to search engines like Google Search Console or Bing Webmaster Tools to help them discover and index your content more efficiently.
package/docs/recipes/custom-fonts.md DELETED
@@ -1,43 +0,0 @@
1
- ---
2
- title: "Recipe: Custom Fonts"
3
- description: "How to add Google Fonts or custom typefaces to your documentation."
4
- ---
5
-
6
- # Adding Custom Fonts
7
-
8
- You can easily change the typography of your `docmd` site using CSS variables and a custom stylesheet.
9
-
10
- ## 1. Select a Font
11
- Go to [Google Fonts](https://fonts.google.com) and select the font you want (e.g., "Poppins"). Copy the `@import` URL.
12
-
13
- ## 2. Create a Custom CSS File
14
- Create a file in your project at `assets/css/typography.css`.
15
-
16
- ```css
17
- /* assets/css/typography.css */
18
- @import url('https://fonts.googleapis.com/css2?family=Poppins:wght@400;600;700&display=swap');
19
-
20
- :root {
21
- /* Override the default sans-serif font variable */
22
- --font-family-sans: 'Poppins', system-ui, -apple-system, sans-serif;
23
- }
24
- ```
25
-
26
- ## 3. Register in Config
27
- Add the file to your `docmd.config.js`:
28
-
29
- ```javascript
30
- module.exports = {
31
- // ...
32
- theme: {
33
- name: 'default',
34
- customCss: [
35
- '/assets/css/typography.css' // Points to your new file
36
- ]
37
- }
38
- // ...
39
- }
40
- ```
41
-
42
- ## 4. Restart
43
- Run `docmd dev`. Your site will now use Poppins!
package/docs/recipes/favicon.md DELETED
@@ -1,38 +0,0 @@
1
- ---
2
- title: "Recipe: Custom Favicon"
3
- description: "How to add a custom favicon to your documentation site."
4
- ---
5
-
6
- # Adding a Custom Favicon
7
-
8
- A favicon is the small icon that appears in the browser tab next to your page title. `docmd` makes it easy to add your own.
9
-
10
- ## 1. Prepare your image
11
- You can use `.ico`, `.png`, or `.svg` files. For the best compatibility, an `.ico` file is recommended.
12
-
13
- ## 2. Add to Assets
14
- Place your image file in your project's assets directory.
15
-
16
- ```bash
17
- # Example structure
18
- my-project/
19
- ├── assets/
20
- │ └── my-icon.ico <-- Your file here
21
- ├── docs/
22
- └── docmd.config.js
23
- ```
24
-
25
- ## 3. Update Configuration
26
- Open `docmd.config.js` and update the `favicon` property with the path relative to the output root.
27
-
28
- ```javascript
29
- module.exports = {
30
- // ...
31
- // Points to site/assets/my-icon.ico
32
- favicon: '/assets/my-icon.ico',
33
- // ...
34
- };
35
- ```
36
-
37
- ## 4. Build
38
- Run `docmd build` (or `docmd dev`). `docmd` will automatically copy your asset file to the site build and link it in the `<head>` of every page.
package/docs/recipes/index.md DELETED
@@ -1,12 +0,0 @@
1
- ---
2
- title: "Recipes to cook best of docmd"
3
- description: "Step-by-step guides for common docmd customizations."
4
- ---
5
-
6
- # Recipes
7
-
8
- Common patterns and "how-to" guides for getting the most out of `docmd`.
9
-
10
- * [**Custom Fonts**](./custom-fonts) - Give your docs a unique personality by loading Google Fonts or local font files.
11
- * [**Landing Pages**](./landing-page) - How to create a beautiful, full-width marketing page using the `noStyle` feature.
12
- * [**Custom Favicon**](./favicon) - Simple steps to adding your brand's icon.
package/docs/recipes/landing-page.md DELETED
@@ -1,46 +0,0 @@
1
- ---
2
- title: "Recipe: Marketing Landing Page"
3
- description: "How to build a custom landing page using noStyle."
4
- ---
5
-
6
- # Creating a Landing Page
7
-
8
- Sometimes you want your `index.html` (the home page) to look completely different from your documentation—like a product marketing page. `docmd` makes this easy with **No-Style Pages**.
9
-
10
- ## The Concept
11
- By adding `noStyle: true` to your frontmatter, `docmd` strips away the sidebar, header, and default CSS, giving you a blank canvas while still keeping helpful meta tags.
12
-
13
- ## Implementation
14
-
15
- Create or edit `docs/index.md`:
16
-
17
- ```html
18
- ---
19
- title: "My Product"
20
- description: " The best product ever."
21
- noStyle: true
22
- components:
23
- meta: true # Keep SEO tags
24
- favicon: true # Keep favicon
25
- scripts: false # Disable default docmd scripts
26
- customHead: |
27
- <style>
28
- body { font-family: sans-serif; margin: 0; }
29
- .hero { background: #111; color: #fff; padding: 100px 20px; text-align: center; }
30
- .btn { background: #3b82f6; color: white; padding: 10px 20px; text-decoration: none; border-radius: 5px; }
31
- </style>
32
- ---
33
-
34
- <div class="hero">
35
- <h1>Welcome to My Product</h1>
36
- <p>The ultimate solution for X, Y, and Z.</p>
37
- <br>
38
- <a href="/getting-started/" class="btn">Read the Docs →</a>
39
- </div>
40
-
41
- <div class="features">
42
- <!-- Your custom HTML features grid here -->
43
- </div>
44
- ```
45
-
46
- This page will be built as `index.html` but will look exactly like your custom HTML, serving as a perfect entry point to your documentation.
package/docs/theming/assets-management.md DELETED
@@ -1,126 +0,0 @@
1
- ---
2
- title: "Assets Management"
3
- description: "Learn how to manage and customize your assets (CSS, JavaScript, images) in your docmd site."
4
- ---
5
-
6
- # Assets Management
7
-
8
- Managing your custom assets (CSS, JavaScript, images) is an important part of customizing your documentation site. `docmd` provides flexible ways to include and manage these assets.
9
-
10
- ## Project Structure
11
-
12
- When you initialize a new project with `docmd init`, it creates the following structure:
13
-
14
- ```
15
- your-project/
16
- ├── assets/ # User assets directory
17
- │ ├── css/ # Custom CSS files
18
- │ ├── js/ # Custom JavaScript files
19
- │ └── images/ # Custom images
20
- ├── docs/ # Markdown content
21
- ├── docmd.config.js
22
- └── ...
23
- ```
24
-
25
- This structure makes it easy to organize and manage your custom assets.
26
-
27
- ## How Assets Are Handled
28
-
29
- There are two main ways to manage assets in your docmd site:
30
-
31
- ### 1. Root-Level Assets Directory (Recommended)
32
-
33
- The simplest and recommended approach is to use the `assets/` directory in your project root:
34
-
35
- **How it works:**
36
- - During the build process, docmd automatically copies everything from your root `assets/` directory to the output `site/assets/` directory
37
- - Your custom assets take precedence over docmd's built-in assets with the same name
38
- - This approach is ideal for GitHub Pages deployments and other hosting scenarios
39
-
40
- **Example workflow:**
41
- 1. Create or modify files in your project's `assets/` directory:
42
- ```
43
- assets/css/custom-styles.css
44
- assets/js/interactive-features.js
45
- assets/images/logo.png
46
- ```
47
-
48
- 2. Reference these files in your config file:
49
- ```javascript
50
- module.exports = {
51
- // ...
52
- theme: {
53
- // ...
54
- customCss: [
55
- '/assets/css/custom-styles.css',
56
- ],
57
- },
58
- customJs: [
59
- '/assets/js/interactive-features.js',
60
- ],
61
- // ...
62
- };
63
- ```
64
-
65
- 3. Use images in your Markdown content:
66
- ```markdown
67
- ![Logo](/assets/images/logo.png)
68
- ```
69
-
70
- 4. Build your site:
71
- ```bash
72
- docmd build
73
- ```
74
-
75
- ### 2. Customizing Default Assets
76
-
77
- If you want to modify docmd's default assets:
78
-
79
- 1. First, build your site normally to generate all assets:
80
- ```bash
81
- docmd build
82
- ```
83
-
84
- 2. Modify the generated files in the `site/assets` directory as needed.
85
-
86
- 3. When rebuilding, use the `--preserve` flag to keep your customized files:
87
- ```bash
88
- docmd build --preserve
89
- ```
90
-
91
- 4. If you want to update to the latest docmd assets (for example, after updating the package), run without the preserve flag:
92
- ```bash
93
- docmd build
94
- ```
95
-
96
- This approach allows you to:
97
- - Get the latest assets by default when you update the package
98
- - Preserve your customizations when needed with `--preserve`
99
- - See which files are being preserved during the build process
100
-
101
- The preservation behavior works with both `build` and `dev` commands:
102
- ```bash
103
- # Preserve custom assets during development
104
- docmd dev --preserve
105
- ```
106
-
107
- ## Asset Precedence
108
-
109
- When multiple assets with the same name exist, docmd follows this precedence order:
110
-
111
- 1. **User assets** from the root `assets/` directory (highest priority)
112
- 2. **Preserved assets** from previous builds (if `--preserve` is enabled, which is the default)
113
- 3. **Built-in assets** from the docmd package (lowest priority)
114
-
115
- This ensures your custom assets always take precedence over default ones.
116
-
117
- ## GitHub Pages Deployment
118
-
119
- When deploying to GitHub Pages, your assets structure is preserved. If you're using a custom domain or GitHub Pages URL, make sure your asset paths are correctly configured.
120
-
121
- For more information on deployment, see the [Deployment](/deployment/) documentation.
122
-
123
- ## Related Topics
124
-
125
- - [Custom CSS & JS](/theming/custom-css-js/) - Learn how to configure custom CSS and JavaScript
126
- - [Theming](/theming/) - Explore other theming options for your documentation site
package/docs/theming/available-themes.md DELETED
@@ -1,77 +0,0 @@
1
- ---
2
- title: "Available Themes"
3
- description: "An overview of the built-in themes provided by docmd."
4
- ---
5
-
6
- # Available Themes
7
-
8
- `docmd` allows you to choose from a selection of built-in themes to quickly change the overall look and feel of your documentation site. You can specify the theme in your config file using the `theme.name` property.
9
-
10
- ```javascript
11
- module.exports = {
12
- // ...
13
- theme: {
14
- name: 'theme-name', // Options: 'default', 'sky', 'ruby', 'retro'
15
- defaultMode: 'light', // or 'dark' to set as landing mode
16
- // ...
17
- },
18
- // ...
19
- };
20
- ```
21
-
22
- ## 1. `default` Theme
23
-
24
- * **`theme.name: 'default'`**
25
- * **Description:** The foundation of all docmd themes. This is not a separate theme but the base styling that's always included regardless of which theme you select. It provides:
26
- * Basic layout structure with sidebar and content area
27
- * Essential typography and spacing
28
- * Core styling for documentation elements like code blocks, tables, and custom containers
29
- * Light and dark mode foundation
30
- * **When to use:** When you want a minimalist, clean interface without additional styling layers. This is the most lightweight option.
31
-
32
- ## 2. `sky` Theme
33
-
34
- * **`theme.name: 'sky'`** (This is the default if `theme.name` is not specified)
35
- * **Description:** A modern theme inspired by popular documentation platforms, with a fresh and airy design. It features:
36
- * A clean, minimalist interface with subtle shadows and rounded corners
37
- * Custom typography with improved readability
38
- * Refined color palette for both light and dark modes
39
- * Enhanced callout and container styles
40
- * Premium documentation feel with careful attention to spacing and contrast
41
- * **When to use:** When you want a premium, polished look for your documentation site.
42
-
43
- ## 3. `ruby` Theme
44
-
45
- * **`theme.name: 'ruby'`**
46
- * **Description:** An elegant, vibrant theme inspired by the precious gemstone. It features:
47
- * Rich, jewel-toned color palette centered around ruby reds and complementary colors
48
- * Sophisticated typography with serif headings and sans-serif body text
49
- * Distinctive card and callout designs with gem-like faceted styling
50
- * Subtle gradients and depth effects that evoke the brilliance of gemstones
51
- * Luxurious dark mode with deep, rich backgrounds and vibrant accent colors
52
- * **When to use:** When you want your documentation to have a distinctive, premium feel with rich colors and elegant typography.
53
-
54
- ## 4. `retro` Theme
55
-
56
- * **`theme.name: 'retro'`**
57
- * **Description:** A nostalgic theme inspired by 1980s-90s computing aesthetics. It features:
58
- * Terminal-style black backgrounds with phosphor green text in dark mode
59
- * Light mode with dark green text on light gray backgrounds
60
- * Monospace typography (Fira Code) for authentic retro feel
61
- * Neon accent colors (cyan, pink, amber) with glow effects
62
- * Animated scanlines and CRT flicker effects
63
- * Terminal-style code blocks with `[TERMINAL]` labels
64
- * Retro-styled containers with pixel-art inspired elements
65
- * Blinking cursor effects on links and active elements
66
- * **When to use:** Perfect for developer tools, gaming documentation, tech blogs with vintage computing focus, or anyone wanting a unique, eye-catching retro aesthetic.
67
-
68
- ## How Themes Work
69
-
70
- Each theme consists of CSS files located within `docmd`'s internal assets. When you select a theme name, `docmd` links the corresponding stylesheet in your site's HTML:
71
-
72
- - `default` theme uses the base CSS with no additional theme stylesheet
73
- - `sky` theme loads `docmd-theme-sky.css` with its custom styling on top of the default CSS
74
- - `ruby` theme loads `docmd-theme-ruby.css` with its custom styling on top of the default CSS
75
- - `retro` theme loads `docmd-theme-retro.css` with its custom styling on top of the default CSS
76
-
77
- You can further customize any chosen theme using the `theme.customCss` option in your config file to add your own overrides or additional styles. See [Custom CSS & JS](/theming/custom-css-js/) for details.
package/docs/theming/custom-css-js.md DELETED
@@ -1,79 +0,0 @@
1
- ---
2
- title: "Custom Styles & Scripts"
3
- description: "Learn how to add your own custom CSS and JavaScript to your docmd site for advanced customization."
4
- ---
5
-
6
- # Custom Styles & Scripts
7
-
8
- While `docmd` themes provide a solid foundation, you can further tailor the appearance and behavior of your site by injecting custom CSS and JavaScript files. This is configured in your config file.
9
-
10
- ## Custom CSS
11
-
12
- You can add one or more custom CSS files using the `theme.customCss` array in your config file.
13
-
14
- ```javascript
15
- module.exports = {
16
- // ...
17
- theme: {
18
- name: 'default',
19
- // ...
20
- customCss: [
21
- '/assets/css/my-branding.css', // Path relative to your site's root
22
- '/css/another-stylesheet.css'
23
- ],
24
- },
25
- // ...
26
- };
27
- ```
28
-
29
- **How it works:**
30
- * Each string in the `customCss` array should be an absolute path from the root of your generated `site/` directory (e.g., if your file is `site/assets/css/my-branding.css`, the path is `/assets/css/my-branding.css`).
31
- * These `<link rel="stylesheet">` tags will be added to the `<head>` of every page *after* the main theme CSS and `highlight.js` CSS. This allows your custom styles to override the default theme styles.
32
-
33
- > **Note:** For information on how to manage your custom asset files (CSS, JS, images), see the [Assets Management](/theming/assets-management/) documentation.
34
-
35
- **Use Cases for Custom CSS:**
36
- * **Overriding CSS Variables:** The `default` theme uses CSS variables extensively. You can redefine these in your custom CSS.
37
- ```css
38
- /* my-branding.css */
39
- :root { /* Light mode overrides */
40
- --primary-color: #D65A31; /* Example: Change primary color */
41
- --font-family-sans: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
42
- --text-color: #222;
43
- }
44
-
45
- body[data-theme="dark"] { /* Dark mode overrides */
46
- --primary-color: #E87A5A;
47
- --bg-color: #121212;
48
- --text-color: #ddd;
49
- }
50
- ```
51
- * **Styling Custom Components:** Add styles for specific elements or components unique to your documentation.
52
- * **Fine-tuning Layout:** Make minor adjustments to spacing, sizing, or layout elements.
53
-
54
- ## Custom JavaScript
55
-
56
- You can add one or more custom JavaScript files using the top-level `customJs` array in your config file.
57
-
58
- ```javascript
59
- module.exports = {
60
- // ...
61
- customJs: [
62
- '/assets/js/my-interactive-script.js', // Path relative to your site's root
63
- '/js/third-party-integration.js'
64
- ],
65
- // ...
66
- };
67
- ```
68
-
69
- **How it works:**
70
- * Each string in the `customJs` array should be an absolute path from the root of your generated `site/` directory.
71
- * These `<script src="..."></script>` tags will be added just before the closing `</body>` tag on every page. This ensures the DOM is loaded before your scripts run and is generally better for page performance.
72
-
73
- **Use Cases for Custom JS:**
74
- * Adding interactive elements (e.g., custom modals, tabs not provided by `docmd`).
75
- * Integrating third-party services or widgets.
76
- * Performing custom DOM manipulations after the page loads.
77
- * Adding simple analytics or tracking snippets if not using a built-in plugin.
78
-
79
- By using `customCss` and `customJs`, you have significant flexibility to extend and personalize your `docmd` site beyond the standard theming options.