{"id":28323645,"url":"https://github.com/barisgit/wikly","last_synced_at":"2026-02-14T03:32:56.514Z","repository":{"id":281931773,"uuid":"946764996","full_name":"barisgit/wikly","owner":"barisgit","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-12T01:37:58.000Z","size":184,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-02T01:02:05.455Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/barisgit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-11T16:33:27.000Z","updated_at":"2025-03-12T01:38:02.000Z","dependencies_parsed_at":"2025-03-12T14:30:38.353Z","dependency_job_id":null,"html_url":"https://github.com/barisgit/wikly","commit_stats":null,"previous_names":["barisgit/wikly"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/barisgit/wikly","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barisgit%2Fwikly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barisgit%2Fwikly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barisgit%2Fwikly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barisgit%2Fwikly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/barisgit","download_url":"https://codeload.github.com/barisgit/wikly/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barisgit%2Fwikly/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261582347,"owners_count":23180575,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-25T16:14:35.894Z","updated_at":"2026-02-14T03:32:51.467Z","avatar_url":"https://github.com/barisgit.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wikly\n\nA command-line tool to export and analyze content from a Wiki.js instance using the GraphQL API. This is a **read-only** tool that will not make any changes to your Wiki.js content.\n\n## Features\n\n- Export pages with metadata and content from Wiki.js\n- Multiple output formats (JSON, Markdown, HTML)\n- Easy to use command-line interface\n- Support for environment variables and configuration files\n- Read-only operation (won't modify your wiki)\n- Export content with original paths and hierarchy\n- Content analysis with Gemini AI to ensure style guide compliance\n\n## Installation\n\n### Using pip\n\n```bash\npip install wikly\n```\n\n### From source\n\n```bash\ngit clone https://github.com/yourusername/wikly.git\ncd wikly\npip install -e .\n```\n\n## Configuration\n\nThere are three ways to configure Wikly:\n\n1. **Configuration File**: Use the `wikly init` command to generate a template configuration file.\n2. **Command Line Options**: Pass options directly when running commands.\n3. **Environment Variables**: Configure through environment variables.\n\nThe tool follows this precedence: Command Line \u003e Config File \u003e Environment Variables\n\n### Configuration File\n\nRun the following command to create a template configuration file:\n\n```bash\nwikly init\n```\n\nThis creates a `wikly_config.yaml` file with the following structure:\n\n```yaml\nwikly:\n  host: https://your-wiki-instance.com\n  api_key: YOUR_API_KEY_HERE\n\nexport:\n  default_format: markdown\n  default_output: wiki_pages\n  delay: 0.1\n  metadata_file: .wikly_export_metadata.json\n\ngemini:\n  api_key: YOUR_GEMINI_API_KEY_HERE\n```\n\nYou can specify a different path for the configuration file:\n\n```bash\nwikly init --path custom_config.yaml\n```\n\n### Environment Variables\n\nSet the following environment variables:\n\n* `WIKLY_HOST`: Base URL of your Wiki.js instance\n* `WIKLY_API_KEY`: API token with appropriate permissions\n* `GEMINI_API_KEY`: Google Gemini API key (optional, for analysis features)\n\nA convenient way to manage these variables is to create a `.env` file in your working directory:\n\n```\nWIKLY_HOST=https://your-wiki-instance.com\nWIKLY_API_KEY=your-api-token\nGEMINI_API_KEY=your-gemini-api-key\n```\n\nThe tool will automatically load these variables when run.\n\n## Usage\n\nAll commands accept a `--config-file` option to specify a custom configuration file:\n\n```bash\nwikly \u003ccommand\u003e --config-file my_config.yaml\n```\n\n### Initialization\n\nGenerate a template configuration file:\n\n```bash\nwikly init\n```\n\nThis command creates three files:\n1. `wikly_config.yaml` - Main configuration file\n2. `wiki_style_guide.md` - Sample style guide for content analysis\n3. `ai_instructions.md` - AI-specific instructions for content analysis\n\nOptions:\n* `--path`: Specify a custom location for the configuration file (default: wikly_config.yaml)\n* `--force`: Force overwrite if the files already exist\n\nThe configuration file includes settings for Wiki.js connection, export options, and AI analysis parameters.\n\n### Test Connection\n\nVerify your Wiki.js connection:\n\n```bash\nwikly test\n```\n\nOptions:\n* `--url`: Override the Wiki.js URL\n* `--token`: Override the API token\n* `--config-file`: Path to custom configuration file\n\n### List Pages\n\nList all pages in your Wiki.js instance:\n\n```bash\nwikly list\n```\n\nOptions:\n* `--url`: Override the Wiki.js URL\n* `--token`: Override the API token\n* `--config-file`: Path to custom configuration file\n\n### Export Pages\n\nExport all pages from Wiki.js:\n\n```bash\nwikly export\n```\n\nOptions:\n* `--url`: Override the Wiki.js URL\n* `--token`: Override the API token\n* `--output`: Custom output location\n* `--delay`: Adjust request delay (seconds)\n* `--debug`: Enable debug output\n* `--format`: Choose output format (json, markdown, html)\n* `--incremental/--full`: Enable/disable incremental export (default: incremental)\n* `--force-full`: Force a full export\n* `--reset-hashes`: Reset all content hashes (forces recomputing)\n* `--metadata-file`: Custom location for metadata file\n* `--config-file`: Path to custom configuration file\n\n### Analyze Content\n\nRun semantic analysis on exported content:\n\n```bash\nwikly analyze\n```\n\nThis command uses the Gemini AI to analyze Wiki.js content against a style guide, identifying issues and suggesting improvements.\n\nOptions:\n* `--format`: Input format (json, markdown)\n* `--output`: Custom output location\n* `--input`: Input file or directory\n* `--api-key`: Google Gemini API key\n* `--style-guide`: Custom path to style guide file\n* `--ai-guide`: Custom path to AI instructions file\n* `--config-file`: Path to custom configuration file\n\nThe analysis process:\n1. Loads content from the specified source (JSON or Markdown files)\n2. Reads the style guide and AI instructions (created by `wikly init`)\n3. Analyzes each page for style compliance\n4. Generates a report with issues and suggestions\n\nResults include:\n- A summary of each page's compliance with the style guide\n- Specific discrepancies with location and severity\n- Suggested corrections for each issue\n- An overall compliance score for each page\n\n### Generate Report\n\nGenerate an HTML report from existing analysis results:\n\n```bash\n# Using an explicit input file\nwikly report analysis_results.json\n\n# Using configuration defaults\nwikly report\n```\n\nThis command takes previously generated analysis results (JSON) and creates a visual HTML report without needing to re-run the analysis.\n\nOptions:\n* `--output`, `-o`: Custom output path for the HTML report (default: analysis_report.html)\n* `--style-guide`: Path to style guide file to include in the report\n* `--config-file`: Path to custom configuration file\n\nIf you don't specify an input file, the command will use the default paths from your configuration. This means you can simply run `wikly report` after running `wikly analyze` to generate an HTML report from the latest analysis results.\n\nThis is useful when:\n- You want to generate a report with different formatting\n- You need to share results with team members\n- You've manually edited the analysis results\n- You want to create multiple report versions from the same analysis\n\n#### Style Guide and AI Instructions\n\nThe `wikly init` command creates two files for content analysis:\n\n1. **Style Guide** (`wiki_style_guide.md`): Contains human-readable guidelines for writing wiki content. This is the primary reference for what \"good\" content looks like.\n\n2. **AI Instructions** (`ai_instructions.md`): Contains instructions specifically for the AI analyzer, such as how to prioritize issues, what context to consider, and special analysis requirements.\n\nYou can customize both files to match your organization's style requirements and content standards.\n\n### Listing Pages (Metadata Only)\n\nTo fetch and save a list of all pages (without content):\n\n```bash\nwikly list --output wiki_pages.json\n```\n\n### Exporting Pages with Content\n\nTo export all pages with their full content:\n\n```bash\nwikly export --output wiki_export.json\n```\n\nBy default, the exporter uses incremental mode, which only fetches content for pages that have been updated since the last export. This significantly speeds up subsequent exports.\n\nThe incremental export also detects local changes to exported files. If you modify a file after exporting it, the exporter will detect the change and re-fetch the content from Wiki.js during the next export.\n\nTo force a full export of all pages:\n\n```bash\nwikly export --force-full\n```\n\n#### Export Formats\n\nYou can export in different formats using the `--format` option:\n\n```bash\n# Export as JSON (default)\nwikly export --format json\n\n# Export as Markdown files\nwikly export --format markdown --output wiki_markdown\n\n# Export as HTML files\nwikly export --format html --output wiki_html\n```\n\n#### Additional Export Options\n\n```bash\n# Set delay between API requests\nwikly export --delay 0.5\n\n# Toggle between incremental and full exports\nwikly export --incremental  # Default, only fetches updated content\nwikly export --full         # Fetches all content\n\n# Force a full export regardless of other settings\nwikly export --force-full\n\n# Reset all content hashes (useful if having issues with local change detection)\nwikly export --reset-hashes\n\n# Specify a custom metadata file location\nwikly export --metadata-file /path/to/metadata.json\n\n# Enable verbose debugging output\nwikly export --debug\n```\n\nThe exporter tracks metadata about previous exports in a `.wikly_export_metadata.json` file, including:\n- The last update time for each page\n- Content hashes to detect local modifications\n- Original paths and titles from Wiki.js\n\nThis allows the exporter to intelligently decide which pages need to be re-fetched during incremental exports, based on both server-side updates and local file changes.\n\n##### Handling Edited Files\n\nWhen you edit a file locally after exporting it, the exporter will detect the changes during the next export by comparing content hashes. There are three possible outcomes:\n\n1. **Re-fetch the page**: By default, the exporter will detect local changes and re-fetch the page from Wiki.js.\n2. **Keep local changes**: You can manually update the metadata file to match your local changes.\n3. **Force reset all hashes**: Use `--reset-hashes` option to force recomputing all content hashes.\n\nFor complex workflows with many local edits, you may want to set up version control on your exported files.\n\n### Analyzing Content for Style Compliance\n\nThe `analyze` command lets you check your wiki content against a style guide using Google's Gemini AI:\n\n```bash\nwikly analyze path/to/exported/content style_guide.md\n```\n\nThis will:\n1. Process all Markdown and HTML files in the specified directory\n2. Compare each file against the provided style guide\n3. Generate a detailed report of discrepancies and suggestions\n4. Save both raw results (JSON) and a readable HTML report\n\n#### Incremental Analysis\n\nBy default, the analyze command uses incremental mode, which only analyzes pages that have changed since the last analysis. This significantly improves performance for large wikis:\n\n```bash\n# Incremental analysis (default)\nwikly analyze --incremental\n\n# Force full analysis of all pages\nwikly analyze --full\n\n# Force a full analysis regardless of other settings\nwikly analyze --force-full\n\n# Reset all content hashes (useful if having issues with local change detection)\nwikly analyze --reset-hashes\n\n# Specify a custom metadata file location\nwikly analyze --metadata-file /path/to/metadata.json\n```\n\nThe analyzer tracks metadata about previous analyses in a `.wikly_analysis_metadata.json` file, including:\n- Content hashes to detect file changes\n- Analysis timestamps for each page\n- Issue counts and compliance scores\n\nThis allows the analyzer to intelligently decide which pages need to be re-analyzed, based on both content changes and previous analysis results.\n\n#### Additional Options\n\n```bash\n# Set a custom output location for results\nwikly analyze content_dir style_guide.md --output analysis.json --report report.html\n\n# Use a specific Gemini model\nwikly analyze content_dir style_guide.md --model gemini-1.5-pro\n\n# Add delay between API calls to avoid rate limits\nwikly analyze content_dir style_guide.md --delay 2.0\n\n# Provide a separate AI-specific guidance file\nwikly analyze content_dir style_guide.md --ai-guide ai_specific_guide.md\n\n# Enable debug output\nwikly analyze content_dir style_guide.md --debug\n```\n\n#### AI Guide\n\nYou can optionally provide an AI-specific guidance file that contains instructions specifically for the AI analyzer, separate from the human-readable style guide. This allows you to:\n\n- Give more technical instructions to the AI without cluttering the human style guide\n- Provide examples of correct and incorrect content for better AI understanding\n- Add contextual information that helps the AI make better judgments\n\nExample usage:\n```bash\nwikly analyze content_dir human_style_guide.md --ai-guide ai_specific_instructions.md\n```\n\n#### Rate Limiting Protection\n\nThe tool implements several strategies to handle Gemini API rate limits:\n\n- Configurable delay between file processing (use `--delay` option)\n- Random jitter added to delays to prevent synchronized requests\n- Exponential backoff for 429 (Too Many Requests) errors\n- Automatic retries when rate limits are hit (up to 5 attempts)\n\nThese features help ensure your analysis completes successfully even with large content sets.\n\n#### Listing Available Models","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarisgit%2Fwikly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbarisgit%2Fwikly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarisgit%2Fwikly/lists"}