diff --git a/docs/_contents/en/articles/importance_of_documentation.md b/docs/_contents/en/articles/importance_of_documentation.md new file mode 100644 index 0000000..55d8af2 --- /dev/null +++ b/docs/_contents/en/articles/importance_of_documentation.md @@ -0,0 +1,154 @@ +--- +title: "The Critical Importance of Documentation in Modern Software Development" +description: "Explore why documentation is crucial for software success, customer experience, and AI development in today's tech landscape." +author: "Saurav Panda" +publishDate: 2024-11-10 +modifiedDate: 2024-11-10 +category: "Technical Insights" +keywords: + - Documentation + - Developer Experience + - Customer Success + - AI Training + - Open Source + - SaaS +--- + +# The Critical Importance of Documentation in Modern Software Development + +Having spent years building developer tools, I've witnessed firsthand how documentation can make or break a software project. It's fascinating how often we prioritize shipping features while pushing documentation to "we'll do it later." But here's the thing - that "later" often comes at a much higher cost than we imagine. + +## The Real Pain of Poor Documentation + +I remember joining a startup where tribal knowledge was the norm. What should have been a two-week onboarding turned into months of piecing together how things worked. This isn't just my story - I've heard similar experiences from countless developers. Here's what we're all dealing with: + +### The Daily Developer Struggle +- We spend nearly a third of our time just trying to understand existing code +- New team members feel lost and overwhelmed +- That quick fix? It takes hours because nobody documented the gotchas + +### The Customer's Perspective +I've been on both sides of this - as a developer and as a user. When documentation is poor: +- Users get frustrated and simply give up +- Support teams get flooded with basic questions +- Customer success becomes more about firefighting than growth +- Users churn because they can't unlock your product's full potential + +## The Hidden Costs of Poor Documentation + +### Developer Time and Resources +- Engineers spend up to 30% of their time searching for information or trying to understand code +- Onboarding new team members takes significantly longer without proper documentation +- Technical debt accumulates as tribal knowledge becomes the primary source of information + +### Customer Experience Impact +- Users abandon products due to confusion and frustration +- Support tickets increase, raising operational costs +- Customer success teams struggle to provide accurate assistance +- Higher churn rates due to poor user experience + +### AI and Machine Learning Challenges +- LLMs trained on outdated or incorrect documentation spread misinformation +- AI assistants struggle to provide accurate, context-aware help +- The gap between code reality and documentation widens as software evolves + +## Documentation as a Growth Driver + +### Enhanced Customer Experience +- Clear documentation reduces friction in user adoption +- Self-service support becomes more effective +- Users feel more confident and empowered +- Higher customer satisfaction and retention rates + +### SEO and Brand Authority +- Well-documented products rank better in search results +- Documentation pages serve as valuable content marketing +- Establishes thought leadership in the industry +- Builds trust with potential customers + +### Open Source Success +- Quality documentation attracts more contributors +- Increases project adoption and community engagement +- Makes your project more discoverable +- Facilitates collaboration across time zones + +## The AI Documentation Challenge + +### Current Problems +- AI models learning from outdated or incorrect documentation +- Inability to verify the accuracy of AI-generated responses +- Disconnect between documentation and actual code implementation +- Difficulty in maintaining up-to-date documentation + +### Future Solutions +- AI-powered documentation generation and validation +- Real-time documentation updates based on code changes +- Automated quality scoring and improvement suggestions +- Enhanced search and discovery through AI understanding + +## Best Practices for Modern Documentation + +### Structure and Organization +- Clear hierarchy and navigation +- Consistent formatting and style +- Version control and change tracking +- Regular audits and updates + +### Content Quality +- Code examples and use cases +- Step-by-step tutorials +- Troubleshooting guides +- API reference documentation + +### User-Centric Approach +- Different documentation levels for various user types +- Interactive examples and playgrounds +- Feedback mechanisms +- Community contribution guidelines + +## The Business Case for Documentation + +### ROI Metrics +- Reduced support costs +- Faster user onboarding +- Improved team productivity +- Higher customer satisfaction scores + +### Competitive Advantage +- Better market positioning +- Increased user trust +- Faster product adoption +- Strong community engagement + +## Why We Built Akiradocs + +After experiencing these documentation challenges repeatedly, we created Akiradocs as an alternative to existing solutions like Nextra. While Nextra provides a solid foundation for documentation sites, we wanted to go further. With Akiradocs, you get: + +- **AI-Powered Documentation:** Not just a static site generator, but an intelligent system that helps you create, maintain, and improve your docs +- **Real-Time Validation:** Catch outdated or incorrect documentation before your users do +- **Smart Search and Discovery:** Help users find exactly what they need, when they need it +- **Automated Quality Checks:** Get suggestions for improving your documentation's clarity and completeness +- **Simple Migration:** Easy transition from Nextra or other documentation platforms + +## The Future of Documentation + +Having worked with various documentation tools and seen their limitations, I'm excited about where we're heading. Imagine documentation that: +- Updates itself as your code evolves +- Learns from how users interact with it +- Provides different levels of detail based on user expertise +- Serves as a reliable knowledge source for AI models + +## Conclusion + +Documentation is not just a technical necessity but a strategic asset that impacts every aspect of software success. As AI continues to reshape the technology landscape, the importance of accurate, up-to-date documentation becomes even more critical. Investing in documentation today means building a stronger foundation for tomorrow's success. + +## Getting Started + +I've been through the documentation improvement journey multiple times, and here's what I've learned works best: +1. Start with an honest audit of your current docs +2. Focus on your users' biggest pain points first +3. Build a sustainable documentation culture +4. Use tools like Akiradocs to automate and improve +5. Keep measuring and iterating + +Remember, great documentation isn't about perfection - it's about continuous improvement. Start where you are, use the tools available, and keep making it better. Your future self (and your users) will thank you. diff --git a/docs/_contents/en/articles/welcome.md b/docs/_contents/en/articles/welcome.md index 4cd9828..2503843 100644 --- a/docs/_contents/en/articles/welcome.md +++ b/docs/_contents/en/articles/welcome.md @@ -1,26 +1,46 @@ --- -title: Welcome to Akira Doc -description: Get started with Akira Docs - Next-gen documentation powered by AI -author: Anonymous +title: "Welcome to Cloud Code AI: Building the Future of AI-Powered Documentation" +description: "Join us on our journey to revolutionizing customer experience with advanced AI documentation tools." +author: "Cloud Code AI Team" publishDate: 2024-11-10 modifiedDate: 2024-11-10 -category: Getting Started +category: "Company Blog" keywords: - - Akira Docs - - Documentation - - AI + - Cloud Code AI + - AI Documentation + - Customer Experience + - AI DevOps --- -# Welcome to Akira Doc +# Welcome to Cloud Code AI -Welcome to Akira Docs, the next-generation documentation platform powered by AI. This template will help you get started with creating your own documentation. +At Cloud Code AI, our mission is to harness the power of artificial intelligence to transform the way developers and organizations operate. Our journey began with the ambitious goal of building an AI DevOps engineer, **Kaizen**, designed to streamline and automate complex development operations. You can explore **Kaizen** at [git.new/kaizen](https://git.new/cloudcodeai). -## Key Features +## Our Evolution -- Easy to customize -- AI-powered search -- Block-based content system -- Responsive design +While our initial focus on creating an AI-driven DevOps engineer laid a strong foundation, we recognized the immense potential in enhancing customer experience through intelligent documentation. This insight led us to pivot and develop an AI-powered documentation tool, **Akiradocs**. Discover **Akiradocs** at [git.new/akiradocs](https://git.new/akiradocs). -> [!info] Getting Started -> Start by customizing this template to match your project's needs! \ No newline at end of file +## What We're Building + +Our current project, **Akiradocs**, is an AI-powered documentation tool designed to simplify and enhance the creation, management, and utilization of documentation. By leveraging AI, we aim to provide: + +- **Smart Content Generation:** Automatically generate high-quality documentation based on your project details. +- **AI-Powered Search:** Enable intuitive and intelligent search capabilities to help users find the information they need quickly. +- **Personalized User Experience:** Tailor the documentation experience to individual user needs, making information more accessible and actionable. +- **Seamless Integration:** Easily integrate with your existing tools and workflows to ensure a smooth and efficient documentation process. + +## Future Innovations + +We're excited about the future of documentation, and we're working on groundbreaking features: + +- **Automated Documentation Generation:** Using advanced AI to automatically create comprehensive documentation from your codebase, ensuring your docs stay in sync with your code. +- **Documentation Quality Scoring:** Implementing an intelligent scoring system that evaluates and helps improve documentation quality, completeness, and clarity. +- **LLM Knowledge Integration:** Developing a revolutionary approach for Large Language Models to learn and understand software systems through documentation, making AI assistance more accurate and context-aware. + +## Our Vision + +At Cloud Code AI, we are committed to improving customer experience by making documentation more accessible, interactive, and intelligent. Our AI-driven approach ensures that both developers and end-users can interact with documentation more efficiently, leading to better product understanding and satisfaction. + +## Get Started + +We invite you to join us on this exciting journey. Whether you're a developer looking for smarter documentation tools or an organization aiming to enhance your customer experience, Cloud Code AI has the solutions you need. Stay tuned for updates, and feel free to reach out to our team for more information. \ No newline at end of file diff --git a/docs/akiradocs.config.json b/docs/akiradocs.config.json index 567ffc7..b38c452 100644 --- a/docs/akiradocs.config.json +++ b/docs/akiradocs.config.json @@ -27,7 +27,7 @@ { "label": "navigation.menu.aiSearch", "href": "/aiSearch", "icon": "/sparkles.svg", "show": true }, { "label": "navigation.menu.docs", "href": "/en/docs", "icon": "/legacy.svg", "show": true }, { "label": "navigation.menu.articles", "href": "/en/articles", "icon": "/articles.svg", "show": true }, - { "label": "navigation.menu.apiReference", "href": "/apiReference", "icon": "/api.svg", "show": true } + { "label": "navigation.menu.apiReference", "href": "/apiReference", "icon": "/api.svg", "show": false } ] } }, diff --git a/docs/compiled/de/articles/_meta.json b/docs/compiled/de/articles/_meta.json index b13d7ca..64682e6 100644 --- a/docs/compiled/de/articles/_meta.json +++ b/docs/compiled/de/articles/_meta.json @@ -4,10 +4,6 @@ "title": "Willkommen bei Akira Doc", "path": "/articles/welcome" }, - "template": { - "title": "Testblogbeitrag", - "path": "/articles/template" - }, "ai_integration": { "title": "Ai Integration", "path": "/articles/ai_integration" diff --git a/docs/compiled/de/articles/template.json b/docs/compiled/de/articles/template.json deleted file mode 100644 index 7569dd9..0000000 --- a/docs/compiled/de/articles/template.json +++ /dev/null @@ -1,169 +0,0 @@ -{ - "title": "Testblogbeitrag", - "description": "Ein Test-Blogbeitrag, um alle Blocktypen zu demonstrieren.", - "author": "Anonymous", - "publishDate": "2024-11-10T00:00:00.000Z", - "modifiedDate": "2024-11-10T00:00:00.000Z", - "heroImage": { - "url": "/blog-hero-image.jpg", - "alt": "Hero image for the blog post", - "caption": "Optional caption for the hero image" - }, - "blocks": [ - { - "id": "1", - "type": "heading", - "content": "Hier ist die Übersetzung ins Deutsche, wobei das ursprüngliche Format beibehalten wird:\n\nBeispielüberschrift Beispiel1", - "metadata": { - "level": 1, - "styles": { - "italic": true, - "underline": true - } - } - }, - { - "id": "2", - "type": "paragraph", - "content": "Hier ist die Übersetzung ins Deutsche, wobei das ursprüngliche Format beibehalten wird:\n\nDieser Absatz ist Teil des Blog-Testeintrags. Er zeigt den Absatzblock." - }, - { - "id": "3", - "type": "code", - "content": "console.log('Alle Blöcke werden getestet');", - "metadata": { - "language": "javascript", - "showLineNumbers": true - } - }, - { - "id": "4", - "type": "image", - "content": "/logo_akiradocs.svg", - "metadata": { - "alt": "Test Image", - "caption": "This is a test image", - "size": "small", - "position": "center" - } - }, - { - "id": "5", - "type": "list", - "content": [ - "Hier ist die Übersetzung ins Deutsche, wobei die ursprüngliche Formatierung beibehalten wird:\n\nArtikel 1", - "Hier ist die Übersetzung ins Deutsche, wobei die ursprüngliche Formatierung beibehalten wird:\n\nArtikel 2", - "Hier ist die Übersetzung ins Deutsche, wobei die ursprüngliche Formatierung beibehalten wird:\n\nArtikel 3" - ], - "metadata": { - "listType": "unordered" - } - }, - { - "id": "6", - "type": "divider", - "content": "" - }, - { - "id": "7", - "type": "table", - "content": "", - "metadata": { - "headers": [ - "Column 1", - "Column 2" - ], - "rows": [ - [ - "Row 1, Cell 1", - "Row 1, Cell 2" - ], - [ - "Row 2, Cell 1", - "Row 2, Cell 2" - ] - ] - } - }, - { - "id": "8", - "type": "blockquote", - "content": "Hier ist ein wörtliches Testzitat." - }, - { - "id": "9", - "type": "toggleList", - "content": "", - "metadata": { - "items": [ - { - "title": "Toggle Item 1", - "content": "Content for toggle item 1" - }, - { - "title": "Toggle Item 2", - "content": "Content for toggle item 2" - } - ] - } - }, - { - "id": "10", - "type": "checkList", - "content": "", - "metadata": { - "checkedItems": [ - { - "text": "Check Item 1", - "checked": true - }, - { - "text": "Check Item 2", - "checked": false - } - ] - } - }, - { - "id": "11", - "type": "video", - "content": "/test_video.mp4", - "metadata": { - "caption": "This is a test video" - } - }, - { - "id": "12", - "type": "audio", - "content": "/audio_de_test.mp3", - "metadata": { - "caption": "This is a test audio" - } - }, - { - "id": "13", - "type": "file", - "content": "/dokument_de_test.pdf", - "metadata": { - "name": "Test Document" - } - }, - { - "id": "14", - "type": "emoji", - "content": "😊", - "metadata": { - "label": "smiling face" - } - }, - { - "id": "15", - "type": "callout", - "content": "Hier ist eine wichtige Warnmeldung.", - "metadata": { - "type": "info", - "title": "Important" - } - } - ] -} \ No newline at end of file diff --git a/docs/compiled/en/articles/_meta.json b/docs/compiled/en/articles/_meta.json index 24f7566..3ac95e5 100644 --- a/docs/compiled/en/articles/_meta.json +++ b/docs/compiled/en/articles/_meta.json @@ -4,10 +4,6 @@ "title": "Welcome to Akira Doc", "path": "/articles/welcome" }, - "template": { - "title": "Test Blog Post", - "path": "/articles/template" - }, "ai_integration": { "title": "Ai Integration", "path": "/articles/ai_integration" diff --git a/docs/compiled/en/articles/template.json b/docs/compiled/en/articles/template.json deleted file mode 100644 index 7e04b82..0000000 --- a/docs/compiled/en/articles/template.json +++ /dev/null @@ -1,165 +0,0 @@ -{ - "title": "Test Blog Post", - "description": "A test blog post to demonstrate all block types.", - "author": "Anonymous", - "publishDate": "2024-11-10T00:00:00.000Z", - "modifiedDate": "2024-11-10T00:00:00.000Z", - "heroImage": { - "url": "/blog-hero-image.jpg", - "alt": "Hero image for the blog post", - "caption": "Optional caption for the hero image" - }, - "blocks": [ - { - "id": "1", - "type": "heading", - "content": "Example Heading Sample1", - "metadata": { - "level": 1, - "styles": { - "italic": true, - "underline": true - } - } - }, - { - "id": "2", - "type": "paragraph", - "content": "This paragraph is part of the test blog post. It demonstrates the paragraph block." - }, - { - "id": "3", - "type": "code", - "content": "console.log('Testing all blocks');", - "metadata": { - "language": "javascript", - "showLineNumbers": true - } - }, - { - "id": "4", - "type": "image", - "content": "/akiradocs_logo.svg", - "metadata": { - "alt": "Test Image", - "caption": "This is a test image", - "size": "small", - "position": "center" - } - }, - { - "id": "5", - "type": "list", - "content": ["Item 1", "Item 2", "Item 3"], - "metadata": { - "listType": "unordered" - } - }, - { - "id": "6", - "type": "divider", - "content": "" - }, - { - "id": "7", - "type": "table", - "content": "", - "metadata": { - "headers": [ - "Column 1", - "Column 2" - ], - "rows": [ - [ - "Row 1, Cell 1", - "Row 1, Cell 2" - ], - [ - "Row 2, Cell 1", - "Row 2, Cell 2" - ] - ] - } - }, - { - "id": "8", - "type": "blockquote", - "content": "This is a test blockquote." - }, - { - "id": "9", - "type": "toggleList", - "content": "", - "metadata": { - "items": [ - { - "title": "Toggle Item 1", - "content": "Content for toggle item 1" - }, - { - "title": "Toggle Item 2", - "content": "Content for toggle item 2" - } - ] - } - }, - { - "id": "10", - "type": "checkList", - "content": "", - "metadata": { - "checkedItems": [ - { - "text": "Check Item 1", - "checked": true - }, - { - "text": "Check Item 2", - "checked": false - } - ] - } - }, - { - "id": "11", - "type": "video", - "content": "/test_video.mp4", - "metadata": { - "caption": "This is a test video" - } - }, - { - "id": "12", - "type": "audio", - "content": "/test_audio.mp3", - "metadata": { - "caption": "This is a test audio" - } - }, - { - "id": "13", - "type": "file", - "content": "/test_document.pdf", - "metadata": { - "name": "Test Document" - } - }, - { - "id": "14", - "type": "emoji", - "content": "😊", - "metadata": { - "label": "smiling face" - } - }, - { - "id": "15", - "type": "callout", - "content": "This is an important callout message.", - "metadata": { - "type": "info", - "title": "Important" - } - } - ] -} \ No newline at end of file diff --git a/docs/compiled/es/articles/_meta.json b/docs/compiled/es/articles/_meta.json index 69efbb3..53dfc20 100644 --- a/docs/compiled/es/articles/_meta.json +++ b/docs/compiled/es/articles/_meta.json @@ -4,10 +4,6 @@ "title": "Bienvenido a Akira Doc", "path": "/articles/welcome" }, - "template": { - "title": "Entrada de prueba del blog", - "path": "/articles/template" - }, "ai_integration": { "title": "Ai Integration", "path": "/articles/ai_integration" diff --git a/docs/compiled/es/articles/template.json b/docs/compiled/es/articles/template.json deleted file mode 100644 index 56c042c..0000000 --- a/docs/compiled/es/articles/template.json +++ /dev/null @@ -1,169 +0,0 @@ -{ - "title": "Entrada de prueba del blog", - "description": "Una entrada de blog de prueba para demostrar todos los tipos de bloque.", - "author": "Anonymous", - "publishDate": "2024-11-10T00:00:00.000Z", - "modifiedDate": "2024-11-10T00:00:00.000Z", - "heroImage": { - "url": "/blog-hero-image.jpg", - "alt": "Hero image for the blog post", - "caption": "Optional caption for the hero image" - }, - "blocks": [ - { - "id": "1", - "type": "heading", - "content": "Encabezado de ejemplo Muestra1", - "metadata": { - "level": 1, - "styles": { - "italic": true, - "underline": true - } - } - }, - { - "id": "2", - "type": "paragraph", - "content": "Este párrafo es parte de la entrada de prueba del blog. Demuestra el bloque de párrafo." - }, - { - "id": "3", - "type": "code", - "content": "console.log('Probando todos los bloques');", - "metadata": { - "language": "javascript", - "showLineNumbers": true - } - }, - { - "id": "4", - "type": "image", - "content": "/logo_akiradocs.svg", - "metadata": { - "alt": "Test Image", - "caption": "This is a test image", - "size": "small", - "position": "center" - } - }, - { - "id": "5", - "type": "list", - "content": [ - "Artículo 1", - "Artículo 2", - "Artículo 3" - ], - "metadata": { - "listType": "unordered" - } - }, - { - "id": "6", - "type": "divider", - "content": "" - }, - { - "id": "7", - "type": "table", - "content": "", - "metadata": { - "headers": [ - "Column 1", - "Column 2" - ], - "rows": [ - [ - "Row 1, Cell 1", - "Row 1, Cell 2" - ], - [ - "Row 2, Cell 1", - "Row 2, Cell 2" - ] - ] - } - }, - { - "id": "8", - "type": "blockquote", - "content": "Esta es una prueba de cita textual." - }, - { - "id": "9", - "type": "toggleList", - "content": "", - "metadata": { - "items": [ - { - "title": "Toggle Item 1", - "content": "Content for toggle item 1" - }, - { - "title": "Toggle Item 2", - "content": "Content for toggle item 2" - } - ] - } - }, - { - "id": "10", - "type": "checkList", - "content": "", - "metadata": { - "checkedItems": [ - { - "text": "Check Item 1", - "checked": true - }, - { - "text": "Check Item 2", - "checked": false - } - ] - } - }, - { - "id": "11", - "type": "video", - "content": "/video_de_prueba.mp4", - "metadata": { - "caption": "This is a test video" - } - }, - { - "id": "12", - "type": "audio", - "content": "/audio_de_prueba.mp3", - "metadata": { - "caption": "This is a test audio" - } - }, - { - "id": "13", - "type": "file", - "content": "/documento_de_prueba.pdf", - "metadata": { - "name": "Test Document" - } - }, - { - "id": "14", - "type": "emoji", - "content": "😊", - "metadata": { - "label": "smiling face" - } - }, - { - "id": "15", - "type": "callout", - "content": "Esta es un mensaje de aviso importante.", - "metadata": { - "type": "info", - "title": "Important" - } - } - ] -} \ No newline at end of file diff --git a/docs/compiled/fr/articles/_meta.json b/docs/compiled/fr/articles/_meta.json index cb61775..e3a0670 100644 --- a/docs/compiled/fr/articles/_meta.json +++ b/docs/compiled/fr/articles/_meta.json @@ -4,10 +4,6 @@ "title": "Bienvenue sur Akira Doc", "path": "/articles/welcome" }, - "template": { - "title": "Voici la traduction en français, avec le formatage d'origine conservé :\n\nTest de billet de blog", - "path": "/articles/template" - }, "ai_integration": { "title": "Ai Integration", "path": "/articles/ai_integration" diff --git a/docs/compiled/fr/articles/template.json b/docs/compiled/fr/articles/template.json deleted file mode 100644 index 20ef6ab..0000000 --- a/docs/compiled/fr/articles/template.json +++ /dev/null @@ -1,169 +0,0 @@ -{ - "title": "Voici la traduction en français, avec le formatage d'origine conservé :\n\nTest de billet de blog", - "description": "Voici la traduction en français, avec le formatage d'origine conservé :\n\nUn article de blog de test pour démontrer tous les types de blocs.", - "author": "Anonymous", - "publishDate": "2024-11-10T00:00:00.000Z", - "modifiedDate": "2024-11-10T00:00:00.000Z", - "heroImage": { - "url": "/blog-hero-image.jpg", - "alt": "Hero image for the blog post", - "caption": "Optional caption for the hero image" - }, - "blocks": [ - { - "id": "1", - "type": "heading", - "content": "Voici la traduction en français tout en conservant le formatage d'origine :\n\nEn-tête d'exemple Exemple1", - "metadata": { - "level": 1, - "styles": { - "italic": true, - "underline": true - } - } - }, - { - "id": "2", - "type": "paragraph", - "content": "Voici la traduction en français, avec le formatage d'origine conservé :\n\nCe paragraphe fait partie de l'entrée de test du blog. Il démontre le bloc de paragraphe." - }, - { - "id": "3", - "type": "code", - "content": "console.log('Testant tous les blocs');", - "metadata": { - "language": "javascript", - "showLineNumbers": true - } - }, - { - "id": "4", - "type": "image", - "content": "/logo_akiradocs.svg", - "metadata": { - "alt": "Test Image", - "caption": "This is a test image", - "size": "small", - "position": "center" - } - }, - { - "id": "5", - "type": "list", - "content": [ - "Voici la traduction en français, en conservant la mise en forme d'origine :\n\nArticle 1", - "Voici la traduction en français, en conservant la mise en forme d'origine :\n\nArticle 2", - "Voici la traduction en français, en conservant la mise en forme d'origine :\n\nArticle 3" - ], - "metadata": { - "listType": "unordered" - } - }, - { - "id": "6", - "type": "divider", - "content": "" - }, - { - "id": "7", - "type": "table", - "content": "", - "metadata": { - "headers": [ - "Column 1", - "Column 2" - ], - "rows": [ - [ - "Row 1, Cell 1", - "Row 1, Cell 2" - ], - [ - "Row 2, Cell 1", - "Row 2, Cell 2" - ] - ] - } - }, - { - "id": "8", - "type": "blockquote", - "content": "Voici une citation textuelle de test." - }, - { - "id": "9", - "type": "toggleList", - "content": "", - "metadata": { - "items": [ - { - "title": "Toggle Item 1", - "content": "Content for toggle item 1" - }, - { - "title": "Toggle Item 2", - "content": "Content for toggle item 2" - } - ] - } - }, - { - "id": "10", - "type": "checkList", - "content": "", - "metadata": { - "checkedItems": [ - { - "text": "Check Item 1", - "checked": true - }, - { - "text": "Check Item 2", - "checked": false - } - ] - } - }, - { - "id": "11", - "type": "video", - "content": "/vidéo_de_test.mp4", - "metadata": { - "caption": "This is a test video" - } - }, - { - "id": "12", - "type": "audio", - "content": "/audio_de_test.mp3", - "metadata": { - "caption": "This is a test audio" - } - }, - { - "id": "13", - "type": "file", - "content": "/document_de_test.pdf", - "metadata": { - "name": "Test Document" - } - }, - { - "id": "14", - "type": "emoji", - "content": "😊", - "metadata": { - "label": "smiling face" - } - }, - { - "id": "15", - "type": "callout", - "content": "Voici un message d'avertissement important.", - "metadata": { - "type": "info", - "title": "Important" - } - } - ] -} \ No newline at end of file diff --git a/packages/akiradocs/akiradocs.config.json b/packages/akiradocs/akiradocs.config.json index a2aa563..57e0fc7 100644 --- a/packages/akiradocs/akiradocs.config.json +++ b/packages/akiradocs/akiradocs.config.json @@ -28,7 +28,7 @@ { "label": "navigation.menu.aiSearch", "href": "/aiSearch", "icon": "/sparkles.svg", "show": true }, { "label": "navigation.menu.docs", "href": "/en/docs", "icon": "/legacy.svg", "show": true }, { "label": "navigation.menu.articles", "href": "/en/articles", "icon": "/articles.svg", "show": true }, - { "label": "navigation.menu.apiReference", "href": "/apiReference", "icon": "/api.svg", "show": true } + { "label": "navigation.menu.apiReference", "href": "/apiReference", "icon": "/api.svg", "show": false } ] } }, diff --git a/packages/apiReference/apiUsage.tsx b/packages/apiReference/apiUsage.tsx new file mode 100644 index 0000000..b245d22 --- /dev/null +++ b/packages/apiReference/apiUsage.tsx @@ -0,0 +1,214 @@ +import React, { useState } from 'react'; +import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'; +import { ClipboardIcon, CheckIcon, PlusIcon, MinusIcon } from '@heroicons/react/24/outline'; +import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter'; +import { oneLight } from 'react-syntax-highlighter/dist/esm/styles/prism'; +import { oneDark } from 'react-syntax-highlighter/dist/esm/styles/prism'; +import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'; +import { useTheme } from 'next-themes'; +import { useAnalytics } from '@/hooks/useAnalytics'; + +interface IncludedParamsType { + [key: string]: string[]; +} + +const generateCode = (language: string, server: any, method: string, path: string, parameters: any[], requestBody: any, includedParams: string[]) => { + const url = `${server.url}/${path}`; + const queryParams = parameters + ?.filter(p => p.in === 'query' && (p.required || includedParams.includes(p.name))) + .map(p => `${p.name}=${p.schema.default || '{value}'}`) + .join('&'); + const fullUrl = queryParams ? `${url}?${queryParams}` : url; + + switch (language) { + case 'javascript': + return generateJavaScriptCode(fullUrl, method, requestBody); + case 'python': + return generatePythonCode(fullUrl, method, requestBody); + case 'curl': + return generateCurlCode(fullUrl, method, requestBody); + default: + return ''; + } +}; + +const generateJavaScriptCode = (url: string, method: string, requestBody: any) => { + let code = `fetch('${url}'`; + if (method !== 'get') { + code += `, { + method: '${method.toUpperCase()}', + headers: { + 'Content-Type': 'application/json'${requestBody ? ',\n \'X-API-Key\': \'YOUR_API_KEY\'' : ''} + }${requestBody ? `, + body: JSON.stringify({ + // Add request body here + })` : ''} +}`; + } + code += `) + .then(response => response.json()) + .then(data => console.log(data)) + .catch(error => console.error('Error:', error));`; + + return code; +}; + +const generatePythonCode = (url: string, method: string, requestBody: any) => { + let code = `import requests + +url = '${url}' +${requestBody ? "headers = {'X-API-Key': 'YOUR_API_KEY'}" : ''} +${requestBody ? ` +data = { + # Add request body here +}` : ''} + +response = requests.${method}(url${requestBody ? ', headers=headers, json=data' : ''}) +print(response.json())`; + + return code; +}; + +const generateCurlCode = (url: string, method: string, requestBody: any) => { + let code = `curl -X ${method.toUpperCase()} '${url}'`; + if (requestBody) { + code += ` \\\n -H 'Content-Type: application/json' \\\n -H 'X-API-Key: YOUR_API_KEY' \\\n -d '{ + // Add request body here + }'`; + } + + return code; +}; + +const CopyButton = ({ text }: { text: string }) => { + const [copied, setCopied] = useState(false); + const { track } = useAnalytics() + const handleCopy = async () => { + track('copy_code_button_click', { + code_type: 'api_usage', + code_text: text + }) + await navigator.clipboard.writeText(text); + setCopied(true); + setTimeout(() => setCopied(false), 2000); + }; + + return ( + + ); +}; + +const ParameterToggle = ({ param, isIncluded, onToggle }: { param: any, isIncluded: boolean, onToggle: (paramName: string) => void }) => ( + +); + +export function ApiUsage({ apiSpec }: { apiSpec: any }) { + const [activeTab, setActiveTab] = useState('javascript'); + const [includedParams, setIncludedParams] = useState({}); + const { theme } = useTheme(); + + if (!apiSpec || !apiSpec.servers || !apiSpec.paths) { + return null; // Return null if there's no data to display + } + + const { servers, paths } = apiSpec; + + const toggleParam = (endpointId: string, paramName: string) => { + setIncludedParams(prev => { + const endpointParams = prev[endpointId] || []; + if (endpointParams.includes(paramName)) { + return { ...prev, [endpointId]: endpointParams.filter(p => p !== paramName) }; + } else { + return { ...prev, [endpointId]: [...endpointParams, paramName] }; + } + }); + }; + + return ( +
+ {Object.entries(paths).map(([path, methods]: [string, any]) => + Object.entries(methods as Record).map(([method, details]) => { + const endpointId = `${method}-${path}`; + const endpointIncludedParams = includedParams[endpointId] || []; + const optionalParameters = details.parameters?.filter((p: any) => !p.required) || []; + + return ( + + + +
+ + JavaScript + Python + cURL + + +
+
+ {['javascript', 'python', 'curl'].map(lang => ( + + + {generateCode(lang, servers[0], method, path, details.parameters, details.requestBody, endpointIncludedParams)} + + + ))} +
+ + {optionalParameters.length > 0 && ( +
+

Optional Parameters:

+
+ {optionalParameters.map((param: any) => ( +
+ toggleParam(endpointId, paramName)} + /> + {param.name} +
+ ))} +
+
+ )} + + + ); + }) + )} +
+ ); +} \ No newline at end of file diff --git a/packages/apiReference/page.tsx b/packages/apiReference/page.tsx new file mode 100644 index 0000000..e36f59c --- /dev/null +++ b/packages/apiReference/page.tsx @@ -0,0 +1,341 @@ +"use client" +import React, { useState, useEffect, useCallback, useRef } from 'react'; +import { Suspense } from 'react' +import LoadingSpinner from '@/components/ui/LoadingSpinner' +import { Tabs} from '@/components/ui/tabs'; +import { ChartBarIcon, ArrowTrendingUpIcon, ShieldCheckIcon, InformationCircleIcon } from '@heroicons/react/24/outline'; +import { motion, AnimatePresence } from 'framer-motion'; +import { ApiUsage } from './apiUsage'; +import { ChevronDownIcon, ChevronRightIcon } from 'lucide-react'; +import { get_api_spec, getApiNavigation } from '@/lib/content'; +import { Header } from '@/components/layout/Header' +import { Footer } from '@/components/layout/Footer' +import { getFooterConfig } from '@/lib/footerConfig'; +import { getHeaderConfig } from '@/lib/headerConfig'; +import { ApiSidebar } from '@/components/layout/Navigation'; + + +interface EndpointSectionProps { + id: string; + method: string; + servers: any; + path: string; + summary: string; + description: string; + parameters: any; + requestBody: any; + security: any; + isProd: boolean; + insights: any; +} + +const Badge = ({ children, color }: { children: React.ReactNode, color: string }) => ( + + {children} + +); + +const MethodBadge = ({ method }: { method: string }) => { + const colors: Record = { + get: 'bg-green-100 text-green-800', + post: 'bg-blue-100 text-blue-800', + put: 'bg-yellow-100 text-yellow-800', + patch: 'bg-orange-100 text-orange-800', + delete: 'bg-red-100 text-red-800', + }; + + return ( + + {method.toUpperCase()} + + ); +}; + +const Parameter = ({ param }: { param: any }) => { + const [isExpanded, setIsExpanded] = useState(false); + + const hasDetails = param.description || (param.schema && (param.schema.enum || param.schema.default)); + + const renderContent = () => ( +
+ {param.name} + + {param.in} + + {param.required && ( + required + )} +
+ ); + + if (!hasDetails) { + return ( +
  • + {renderContent()} +
    • + ); + } + + return ( + +
    setIsExpanded(!isExpanded)} + > + {renderContent()} + {isExpanded ? ( + + ) : ( + + )} +
    + + {isExpanded && ( + + {param.description &&

    {param.description}

    } + {param.schema && param.schema.enum && ( +

    + Possible values: + + {param.schema.enum.map((value: string, index: number) => ( + {value} + ))} + +

    + )} + {param.schema && param.schema.default && ( +

    + Default: + + {param.schema.default} + +

    + )} +     + )} +     +     + ); +}; + +const EndpointSection = ({ + id, + method, + servers, + path, + summary, + description, + parameters, + requestBody, + security, + isProd, + insights +}: EndpointSectionProps) => ( +
    +
    +
    +

    {summary}

    +

    + + {path} +

    +

    {description}

    + {security && security.length > 0 && ( +

    Requires Authentication

    + )} +
    + + {parameters && parameters.length > 0 && ( +
    +

    Parameters:

    +
      + {parameters.map((param: any, index: number) => ( + + ))} +
    +
    + )} + + {/* {requestBody && ( +
    +

    Request Body:

    +

    JSON object containing:

    +
      + {Object.entries(requestBody.content['application/json'].schema.properties).map(([key, value]) => ( +
    • + {key} + {value.type && ({value.type})} + {value.description && - {value.description}} +
      • + ))} +
    +
    + )} */} + + {!isProd && insights && ( +
    +

    Development Insights

    + + {insights.performance_insights && ( +
    +
    + + Performance Insights +
    +
      + {insights.performance_insights.map((insight: any, index: number) => ( +
    • + {insight.insight}: {insight.recommendation} +
      • + ))} +
    +
    + )} + + {insights.security_insights && ( +
    +
    + + Security Insights +
    +
      + {insights.security_insights.map((insight: any, index: number) => ( +
    • + {insight.insight}: {insight.recommendation} +
      • + ))} +
    +
    + )} + + {insights.optimization_insights && ( +
    +
    + + Optimization Insights +
    +
      + {insights.optimization_insights.map((insight: any, index: number) => ( +
    • + {insight.insight}: {insight.recommendation} +
      • + ))} +
    +
    + )} + + {insights.additional_metadata && ( +
    +
    + + Additional Metadata +
    +
      + {Object.entries(insights.additional_metadata).map(([key, value]) => ( +
    • + {key}: { + typeof value === 'object' && value !== null + ? JSON.stringify(value) + : String(value) + } +
      • + ))} +
    +
    + )} +
    + )} +
    +
    + +
    +
    +); + +export default function Page() { + const [apiSpec, setApiSpec] = useState(null) + const [activeTab, setActiveTab] = useState('formatted'); + const textareaRef = useRef(null); + const headerConfig = getHeaderConfig(); + const footerConfig = getFooterConfig(); + const locale = 'en' + + const FormattedDocs = useCallback(() => ( + <> + {Object.entries(apiSpec.paths).map(([path, methods]) => + Object.entries(methods as Record).map(([method, details]) => ( + + )) + )} + + ), [apiSpec]); + + + useEffect(() => { + setApiSpec(get_api_spec()) + }, []) + + useEffect(() => { + if (textareaRef.current && apiSpec) { + textareaRef.current.value = JSON.stringify(apiSpec, null, 2); + } + }, [apiSpec]); + + if (!apiSpec) { + return
    Loading...
    ; + } + + return ( + }> + +
    +
    +
    + +
    + +
    +
    +
    +
    +

    {apiSpec.info.title}

    + v{apiSpec.info.version} +
    + {apiSpec.info.description && ( +

    {apiSpec.info.description}

    + )} +
    +
    +
    + +     +
    +
    +
    +     + ); +} \ No newline at end of file diff --git a/packages/create-app/package.json b/packages/create-app/package.json index 74ca09f..7bc576a 100644 --- a/packages/create-app/package.json +++ b/packages/create-app/package.json @@ -1,6 +1,6 @@ { "name": "create-akiradocs", - "version": "1.0.49", + "version": "1.0.50", "description": "Create Akira Docs documentation sites with one command", "main": "./dist/index.js", "type": "module", diff --git a/packages/create-app/src/index.ts b/packages/create-app/src/index.ts index 80035dd..6c6d26f 100644 --- a/packages/create-app/src/index.ts +++ b/packages/create-app/src/index.ts @@ -21,6 +21,7 @@ interface ConfigAnswers { googleAnalyticsId?: string; enableAnalytics: boolean; enableAutoTranslate: boolean; + apiReference: boolean; } async function promptConfigQuestions() { @@ -178,10 +179,11 @@ async function main() { try { let editorResponse; let configAnswers; - + let apiReferenceResponse; if (options.yes) { // Use default values without prompting editorResponse = { includeEditor: true }; + apiReferenceResponse = { includeApiReference: false }; configAnswers = { siteTitle: 'My Documentation', siteDescription: 'Documentation powered by Akira Docs', @@ -191,7 +193,8 @@ async function main() { linkedinUrl: '', enableAnalytics: false, googleAnalyticsId: '', - enableAutoTranslate: false + enableAutoTranslate: false, + apiReference: false }; } else { // Existing prompt flow @@ -202,6 +205,13 @@ async function main() { initial: true, }); + apiReferenceResponse = await enquirer.prompt<{ includeApiReference: boolean }>({ + type: 'confirm', + name: 'includeApiReference', + message: 'Would you like to include the API reference template?', + initial: false, + }); + configAnswers = await promptConfigQuestions(); } @@ -235,6 +245,10 @@ async function main() { } } + if (apiReferenceResponse.includeApiReference) { + await copyDir(path.join(targetDir+'/src/app/apiReference', '../template/apiReference'), targetDir); + } + spinner.succeed(chalk.green('Project created successfully!')); console.log('\nNext steps:'); diff --git a/packages/create-app/tsup.config.ts b/packages/create-app/tsup.config.ts index 9ad1678..5436f1e 100644 --- a/packages/create-app/tsup.config.ts +++ b/packages/create-app/tsup.config.ts @@ -21,6 +21,7 @@ export default defineConfig({ // Copy main template await copyDir('../akiradocs', './template/default'); await copyDir('../editor', './template/editor'); + await copyDir('../apiReference', './template/apiReference'); // Copy main README and gifs folder const rootDir = path.resolve(__dirname, '../..');