Công cụ và plugin

Chọn đúng công cụ và plugin có thể nâng cao đáng kể hiệu suất biên soạn và chất lượng tài liệu Markdown. Hướng dẫn này giới thiệu các nhóm công cụ giúp bạn xây dựng workflow Markdown hoàn chỉnh.

Trình soạn thảo khuyến nghị

Trình soạn mã chuyên nghiệp

Visual Studio Code

Đặc điểm: Miễn phí, đa nền tảng, nhiều plugin

Khuyến nghị plugin:
- Markdown All in One: Hỗ trợ Markdown toàn diện
- Markdown Preview Enhanced: Tăng cường xem trước
- markdownlint: Kiểm tra cú pháp/quy phạm
- Paste Image: Dán ảnh nhanh
- Table Editor: Chỉnh sửa bảng trực quan
- Math to Image: Chuyển công thức thành ảnh

Ví dụ cấu hình:

{
  "markdown.preview.fontSize": 14,
  "markdown.preview.lineHeight": 1.6,
  "markdown.extension.toc.levels": "1..6",
  "markdown.extension.print.absoluteImgPath": false,
  "[markdown]": {
    "editor.wordWrap": "on",
    "editor.lineNumbers": "on",
    "editor.quickSuggestions": false
  }
}

Typora

Đặc điểm: WYSIWYG, giao diện tối giản, nhiều theme

Chức năng chính:
- Xem trước thời gian thực
- Hỗ trợ công thức
- Tích hợp vẽ sơ đồ
- Xuất nhiều định dạng
- Tự động sao chép ảnh
- Chỉnh sửa bảng trực quan

Mark Text

Đặc điểm: Mã nguồn mở, xem trước realtime, hiệu năng tốt

Tính năng cốt lõi:
- Kết xuất xem trước realtime
- Chế độ tập trung
- Hỗ trợ công thức toán
- Hỗ trợ lưu đồ
- Nhiều định dạng xuất
- Tùy biến theme

Trình soạn trực tuyến

StackEdit

Đặc điểm: Dựa trên trình duyệt, đồng bộ đám mây, cộng tác

Điểm nổi bật:
- Đồng bộ realtime với Google Drive, Dropbox
- Xuất bản lên GitHub, nền tảng blog
- Hỗ trợ chỉnh sửa offline
- Công thức và biểu đồ
- Cộng tác biên tập
- Lịch sử phiên bản

Dillinger

Đặc điểm: Giao diện đơn giản, tích hợp đa nền tảng

Tích hợp:
- GitHub
- Dropbox
- Google Drive
- OneDrive
- Hỗ trợ xuất HTML, PDF
- Xem trước realtime

HackMD

Đặc điểm: Cộng tác nhóm, trình chiếu

Tính năng cộng tác:
- Nhiều người biên tập realtime
- Bình luận
- Kiểm soát phiên bản
- Quản lý quyền
- Chế độ trình chiếu
- Chế độ sách

Công cụ xem trước và chuyển đổi

Trình tạo site tĩnh

VitePress

Đặc điểm: Hệ sinh thái Vue, hiệu năng tốt, hiện đại

// .vitepress/config.js
export default {
  title: 'My Documentation',
  description: 'A VitePress site',
  
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' }
    ],
    
    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          items: [
            { text: 'Introduction', link: '/guide/introduction' },
            { text: 'Installation', link: '/guide/installation' }
          ]
        }
      ]
    }
  },
  
  markdown: {
    math: true,
    mermaid: true,
    lineNumbers: true
  }
}

GitBook

Đặc điểm: Giao diện đẹp, cộng tác nhóm, quản lý phiên bản

Tính năng:
- Trải nghiệm đọc hiện đại
- Cộng tác nhóm
- Xuất nhiều định dạng
- Tìm kiếm
- Tích hợp phân tích
- Tạo tài liệu API

Docusaurus

Đặc điểm: Mã nguồn mở từ Facebook, hệ sinh thái React, đa ngôn ngữ

// docusaurus.config.js
module.exports = {
  title: 'My Site',
  tagline: 'The tagline of my site',
  url: 'https://your-docusaurus-test-site.com',
  
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
        },
        blog: {
          showReadingTime: true,
          editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/blog/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],
  
  themeConfig: {
    navbar: {
      title: 'My Site',
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
      },
    },
  },
};

Công cụ chuyển đổi định dạng

Pandoc

Đặc điểm: Bộ chuyển đổi đa năng, CLI, nhiều định dạng

# Chuyển Markdown sang PDF
pandoc document.md -o document.pdf

# Chuyển Markdown sang Word
pandoc document.md -o document.docx

# Chuyển Markdown sang HTML (tùy biến CSS)
pandoc document.md -s --css=style.css -o document.html

# Chuyển đổi hàng loạt
find . -name "*.md" -exec pandoc {} -o {}.pdf \;

# Dùng template
pandoc document.md --template=template.html -o output.html

# Tạo mục lục
pandoc document.md --toc --toc-depth=3 -o document.pdf

markdownlint

Đặc điểm: Kiểm tra cú pháp, tiêu chuẩn thống nhất, sửa lỗi tự động

# Cài đặt
npm install -g markdownlint-cli

# Kiểm tra một tệp
markdownlint README.md

# Kiểm tra thư mục
markdownlint docs/

# Sửa tự động
markdownlint --fix *.md

# Dùng tập tin cấu hình
markdownlint --config .markdownlint.json docs/

Ví dụ cấu hình:

{
  "default": true,
  "MD013": {
    "line_length": 120,
    "code_blocks": false,
    "tables": false
  },
  "MD033": {
    "allowed_elements": ["div", "span", "img", "a"]
  },
  "MD041": false
}

Công cụ hình ảnh và media

Công cụ xử lý ảnh

PicGo

Đặc điểm: Tải lên tự động, đa nền tảng, mở rộng plugin

Hỗ trợ nền tảng:
- Qiniu Cloud
- Tencent Cloud COS
- UpYun
- GitHub
- Aliyun OSS
- Imgur
- Tự cấu hình upload

Ví dụ cấu hình:

{
  "picBed": {
    "uploader": "github",
    "github": {
      "repo": "username/image-repo",
      "token": "your_github_token",
      "path": "images/",
      "customUrl": "https://cdn.jsdelivr.net/gh/username/image-repo",
      "branch": "main"
    }
  },
  "settings": {
    "autoRename": true,
    "uploadNotification": true
  }
}

ImageOptim / TinyPNG

Đặc điểm: Nén ảnh, giảm dung lượng, giữ chất lượng

# Dùng ImageOptim CLI
imageoptim *.png *.jpg

# Dùng TinyPNG API
curl --user api:YOUR_API_KEY \
     --data-binary @original.png \
     --output compressed.png \
     https://api.tinify.com/shrink

Công cụ tạo sơ đồ

draw.io (diagrams.net)

Đặc điểm: Miễn phí, mạnh mẽ, xuất nhiều định dạng

Tình huống sử dụng:
- Sơ đồ kiến trúc hệ thống
- Thiết kế lưu đồ
- Biểu đồ UML
- Sơ đồ mạng
- Mindmap
- Thiết kế prototype

Excalidraw

Đặc điểm: Phong cách vẽ tay, cộng tác, dễ dùng

Tính năng nổi bật:
- Biểu đồ phong cách vẽ tay
- Cộng tác realtime
- Dùng offline
- Xuất PNG/SVG
- Quản lý thư viện
- Canvas không giới hạn

Nền tảng quản lý tài liệu

Công cụ cộng tác nhóm

Notion

Đặc điểm: Không gian làm việc hợp nhất, cơ sở dữ liệu, nhiều template

Chức năng tài liệu:
- Cấu trúc trang phân cấp
- Cộng tác realtime
- Tích hợp cơ sở dữ liệu
- Hệ thống template
- Hỗ trợ đa phương tiện
- Tích hợp API

Confluence

Đặc điểm: Cấp doanh nghiệp, quản lý quyền, tích hợp mạnh

Tính năng doanh nghiệp:
- Kiểm soát quyền nâng cao
- Quy trình phê duyệt
- Tùy biến thương hiệu
- Tích hợp doanh nghiệp
- Tìm kiếm nâng cao
- Báo cáo phân tích

GitBook

Đặc điểm: Thân thiện với dev, kiểm soát phiên bản, giao diện đẹp

Ưu điểm cốt lõi:
- Tích hợp Git
- Lịch sử phiên bản
- Cộng tác nhóm
- Tên miền tùy chỉnh
- Tìm kiếm
- Số liệu phân tích

Nền tảng xuất bản

GitHub Pages

Đặc điểm: Lưu trữ miễn phí, kiểm soát phiên bản, miền tùy chỉnh

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    
    - name: Setup Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '16'
        
    - name: Install dependencies
      run: npm install
      
    - name: Build
      run: npm run build
      
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./dist

Netlify

Đặc điểm: Triển khai nhanh, CDN tăng tốc, xử lý form

# netlify.toml
[build]
  publish = "dist"
  command = "npm run build"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

[build.environment]
  NODE_VERSION = "16"

Vercel

Đặc điểm: Triển khai không cấu hình, CDN toàn cầu, preview deploy

{
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/static-build",
      "config": {
        "distDir": "dist"
      }
    }
  ],
  "routes": [
    {
      "handle": "filesystem"
    },
    {
      "src": "/(.*)",
      "dest": "/index.html"
    }
  ]
}

Công cụ tự động hóa

Tích hợp CI/CD

GitHub Actions

Ví dụ workflow:

name: Documentation Build and Deploy

on:
  push:
    branches: [ main ]
    paths: [ 'docs/**' ]
  pull_request:
    branches: [ main ]
    paths: [ 'docs/**' ]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    
    - name: Lint Markdown
      uses: articulate/actions-markdownlint@v1
      with:
        config: .markdownlint.json
        files: 'docs/**/*.md'

  build:
    needs: lint
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    
    - name: Setup Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '16'
        cache: 'npm'
        
    - name: Install dependencies
      run: npm ci
      
    - name: Build VitePress
      run: npm run docs:build
      
    - name: Upload artifact
      uses: actions/upload-pages-artifact@v1
      with:
        path: docs/.vitepress/dist

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v1

Pre-commit Hooks

Tập tin cấu hình .pre-commit-config.yaml:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
      
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.32.2
    hooks:
      - id: markdownlint
        args: ['--fix']
        
  - repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
      - id: black
        language_version: python3
        
  - repo: local
    hooks:
      - id: docs-build
        name: Build documentation
        entry: npm run docs:build
        language: system
        files: '^docs/.*\.md$'
        pass_filenames: false

Công cụ sinh tài liệu

Tự động sinh tài liệu API

// Dùng JSDoc để sinh tài liệu API
/**
 * Tạo người dùng mới
 * @param {Object} userData - Dữ liệu người dùng
 * @param {string} userData.name - Tên người dùng
 * @param {string} userData.email - Địa chỉ email
 * @param {string} [userData.role=user] - Vai trò người dùng
 * @returns {Promise<Object>} Đối tượng người dùng được tạo
 * @example
 * const user = await createUser({
 *   name: 'Zhang San',
 *   email: 'zhangsan@example.com'
 * });
 */
async function createUser(userData) {
  // Triển khai mã...
}

# Sinh tài liệu
jsdoc src/ -d docs/api/ -c jsdoc.conf.json

Tài liệu OpenAPI/Swagger

# openapi.yaml
openapi: 3.0.0
info:
  title: API Quản lý người dùng
  version: 1.0.0
  description: RESTful API cho hệ thống quản lý người dùng

paths:
  /users:
    post:
      summary: Tạo người dùng mới
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: Tạo người dùng thành công
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: "12345"
        name:
          type: string
          example: "Zhang San"
        email:
          type: string
          format: email
          example: "zhangsan@example.com"
    
    CreateUserRequest:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          default: "user"

Công cụ tối ưu hiệu năng

Tối ưu build

Script tối ưu ảnh

// optimize-images.js
const sharp = require('sharp');
const fs = require('fs');
const path = require('path');

async function optimizeImages(dir) {
  const files = fs.readdirSync(dir);
  
  for (const file of files) {
    const filePath = path.join(dir, file);
    const stat = fs.statSync(filePath);
    
    if (stat.isDirectory()) {
      await optimizeImages(filePath);
    } else if (/\.(jpg|jpeg|png)$/i.test(file)) {
      const outputPath = filePath.replace(/\.(jpg|jpeg|png)$/i, '.webp');
      
      await sharp(filePath)
        .webp({ quality: 80 })
        .toFile(outputPath);
        
      console.log(`Tối ưu: ${file} -> ${path.basename(outputPath)}`);
    }
  }
}

optimizeImages('./docs/assets/images');

Script build tài liệu

// build-docs.js
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');

function buildDocs() {
  console.log('📝 Bắt đầu build tài liệu...');
  
  // 1. Kiểm tra cú pháp Markdown
  console.log('🔍 Kiểm tra cú pháp Markdown...');
  execSync('markdownlint docs/', { stdio: 'inherit' });
  
  // 2. Tối ưu hình ảnh
  console.log('🖼️ Tối ưu hình ảnh...');
  execSync('node optimize-images.js', { stdio: 'inherit' });
  
  // 3. Build site tĩnh
  console.log('🏗️ Build site tĩnh...');
  execSync('vitepress build docs', { stdio: 'inherit' });
  
  // 4. Sinh sitemap
  console.log('🗺️ Sinh sitemap...');
  generateSitemap();
  
  console.log('✅ Hoàn tất build tài liệu!');
}

function generateSitemap() {
  const baseUrl = 'https://yoursite.com';
  const pages = findMarkdownFiles('./docs');
  
  const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
${pages.map(page => `  <url>
    <loc>${baseUrl}${page}</loc>
    <lastmod>${new Date().toISOString().split('T')[0]}</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
  </url>`).join('\n')}
</urlset>`;

  fs.writeFileSync('./docs/.vitepress/dist/sitemap.xml', sitemap);
}

function findMarkdownFiles(dir, basePath = '') {
  const files = [];
  const items = fs.readdirSync(dir);
  
  for (const item of items) {
    const fullPath = path.join(dir, item);
    const relativePath = path.join(basePath, item);
    
    if (fs.statSync(fullPath).isDirectory()) {
      files.push(...findMarkdownFiles(fullPath, relativePath));
    } else if (item.endsWith('.md') && item !== 'README.md') {
      const urlPath = relativePath
        .replace(/\.md$/, '.html')
        .replace(/\\/g, '/');
      files.push('/' + urlPath);
    }
  }
  
  return files;
}

buildDocs();

Hướng dẫn chọn công cụ

Chọn công cụ theo nhu cầu

## Viết blog cá nhân
Gợi ý kết hợp:
- Trình soạn: Typora hoặc Mark Text
- Triển khai: GitHub Pages + Jekyll
- Ảnh: PicGo + GitHub
- Phiên bản: Git

## Cộng tác tài liệu nhóm
Gợi ý kết hợp:
- Nền tảng: Notion hoặc GitBook
- Trình soạn: VS Code + plugin
- Phiên bản: Git + GitHub
- Tự động hóa: GitHub Actions

## Website tài liệu kỹ thuật
Gợi ý kết hợp:
- Trình tạo: VitePress hoặc Docusaurus
- Trình soạn: VS Code
- Triển khai: Netlify hoặc Vercel
- Sơ đồ: Mermaid + draw.io

## Tài liệu API
Gợi ý kết hợp:
- Công cụ: Swagger/OpenAPI
- Sinh tài liệu: Redoc hoặc SwaggerUI
- Tích hợp: Postman
- Kiểm thử: Newman

## Bài báo học thuật
Gợi ý kết hợp:
- Trình soạn: Typora + Pandoc
- Công thức: MathJax/KaTeX
- Trích dẫn: Zotero
- Chuyển đổi: Pandoc LaTeX

So sánh chi phí

Loại công cụ	Miễn phí	Trả phí	Bản doanh nghiệp
Trình soạn	VS Code, Mark Text	Typora (¥89)	-
Lưu trữ	GitHub Pages	Netlify Pro (¥190/tháng)	Tùy chỉnh doanh nghiệp
Cộng tác	GitHub	Notion (¥64/người/tháng)	Confluence (¥42/người/tháng)
Lưu trữ ảnh	GitHub	Qiniu (¥0.1/GB)	Cloud riêng doanh nghiệp
Tên miền	github.io	Miền tùy chỉnh (¥60/năm)	Miền doanh nghiệp

Cú pháp liên quan

• Nhúng HTML - Tăng cường HTML
• Công thức toán - Biểu thức LaTeX
• Lưu đồ - Vẽ biểu đồ
• Thực hành tốt nhất - Gợi ý soạn tài liệu

Khuyến nghị tổng kết

Cấu hình khuyến nghị cho người mới

🚀 Gói bắt đầu nhanh:
1. Trình soạn: VS Code + Markdown All in One
2. Xem trước: plugin realtime preview
3. Phiên bản: Git + GitHub
4. Triển khai: GitHub Pages
5. Ảnh: tải trực tiếp vào repo

💰 Chi phí: hoàn toàn miễn phí
⏱️ Thời gian học: 1-2 giờ
🎯 Phù hợp: blog cá nhân, tài liệu dự án nhỏ

Cấu hình khuyến nghị nâng cao

⚡ Gói chuyên nghiệp:
1. Trình soạn: Typora + VS Code
2. Trình tạo: VitePress
3. Ảnh: PicGo + Cloud Storage
4. Cộng tác: GitHub + Issues
5. Tự động hóa: GitHub Actions
6. Giám sát: Google Analytics

💰 Chi phí: ¥200-500/năm
⏱️ Thời gian học: 1-2 ngày
🎯 Phù hợp: nhóm kỹ thuật, dự án nguồn mở

Cấu hình cấp doanh nghiệp

🏢 Gói doanh nghiệp:
1. Nền tảng: Confluence hoặc GitBook
2. Biên tập: VS Code + plugin nhóm
3. Phiên bản: Git cấp doanh nghiệp
4. Triển khai: cloud riêng + CDN
5. Cộng tác: quản lý quyền đầy đủ
6. Tích hợp: CI/CD + giám sát/cảnh báo

💰 Chi phí: ¥5000-20000/năm
⏱️ Thời gian triển khai: 1-2 tuần
🎯 Phù hợp: doanh nghiệp lớn, tài liệu sản phẩm

Bằng cách lựa chọn và cấu hình hợp lý các công cụ này, bạn có thể xây dựng workflow tài liệu Markdown hiệu quả và chuyên nghiệp, nâng cao đáng kể hiệu suất tạo và duy trì tài liệu.